elementary-dev-community team mailing list archive

[Daniel Foré <daniel@xxxxxxxxxxxxxxxx>]

Well I can tell you right now there's a lot of very non-hypothetical concerns to address. 

The guide has a lot of "what just happened" moments where things aren't explained at all and it's very difficult to follow in many places. (Something I think you admitted yourself in a previous mail).

we have a lot of definitely-not-best-practice moments. There's actually part of the guide where we say "now that you know how to do this, don't ever do this". We need to make sure we're instructing people how to do things properly. Teaching the wrong way to do things leaves us worse off than not having a guide at all.

It's a good start, but it's not a good guide. I would understand if it just needed a little cleaning up, but it's in much worse shape than that. It's not ready for public consumption. 

Best Regards,
Daniel Foré

www.elementaryos.org

El feb 21, 2012, a las 10:40 a.m., Сергей <shnatsel@xxxxxxxxx> escribió:

> Regarding addressing some items first... I agree that there are some critical things to be addressed, but there will always be room for improvement, and polishing some unused doc over and over to suit some hypothetical concerns is really, really boring. I suggest we release a beta so we can get some real-life testing, some real issues to fix and some motivation to work on the doc. 
> 
> Also, keep in mind the guy who just learned something is the best at explaining how to learn that something. Moreover, he's usually willing to do this, unlike developers of the something who hate writing documentation. 
> 
> Actually, +1 to leaving the doc editable for everybody because of that - I didn't even include this option in the initial post, thought I always leave all elementary-related docs editable for everybody (wiki admin habit) and I've never ever had any cases of vandalism; I even got some useful suggestions right in the docs.
> 
> --
> shnatsel