Hi all.
Being very new to SS, I have recently been wading through any and all documentation I can get a hold of. I'm exhausted!
I agree wholeheartedly agree that (i) contributing needs to be easier to understand and do (ii) the existing documentation is fragmented.
A number of other thoughts have come to mind about how to document SS. Allow me to pose questions these thoughts have stimulated:
(1) What are the end goals of the documentation ?
(2) What is(are) the target audience(s) for the documentation ?
(3) How much documentation of "external" tools and notions (ie: git, Github, composer, packagist, PHPDoc, SemVer, YML, XML, PHP, HTML, CSS,JS, Windows vs. OSX vs. *nix, OOP, OODBs,...) should be included ?
(4) What organising principles can be used to avoid fragmentation and encourage adherence to the "DRY" principle ?
(5) How can documentation be organised so that as SS changes it is relatively easy to update ?
(6) How can the valuable information in the 2009 Complete Guide and the 2011 Beginner's Guide be more fully incorporated ?
(7) Should SS aim for a comprehensive, authoritative guide, released once every MAJOR version ?
In my opinion, in addition to various "how tos", there is a serious need for more developer documentation of a "top down" character so that someone completely new to SS can get oriented within the overall architecture much more easily. Such a top down view would help new web developers as much as it would help experienced ones.
What do you all think ?
David.