(phew - long message but I think it's worth it ;-) Hi Felix,
Thanks for your proposal - the overall plan looks good to me, but I'd like the Sling community to agree on some basic principles for how we handle documentation. I'll reformulate below what I already said a while ago (http://markmail.org/message/vchn4e5fih4ktqup). The motivation for this is having been burned with documentation efforts in the Cocoon project (among others), where for a long time we were chasing the elusive goal of "documenting everything precisely", and limited resources (as in any project) made it impossible to write everything. And above all impossible to make sure the docs are in sync with ongoing developments: no one has time to proofread all docs when doing a release here. The result was, at some point, a set of inconsistent documentation where it was very hard to tell the wheat from the chaff. This is by the way the exact situation of our website at the moment, although we have better excuses, being a young project with a recent important redesign. So, for me, a major goal is to create *maintainable* documentation, avoiding manual work as much as possible. An excellent example of documentation that doesn't rot is the way the "Lucene in Action" book uses actual unit tests for most or all of its examples [1]: assuming the exact examples included in the docs are executed regularly, those docs cannot rot. [1] http://www.manning.com/hatcher2/excerpt_about.html That being said, here are my suggestions for guiding principles for our documentation efforts. Discussion is welcome, of course. == Sling Developer Usability Principles == 0) Create as little documentation as possible: every line of documentation that's not automatically generated has to be maintained. 1) One task, one document: avoid "big" docs that explain too many things. The goal is to be able to say "this document is totally obsolete" when the time comes, rather than " this doc has some obsolete stuff in it". 2) Do not duplicate info in the docs - I'd rather point people to (readable) code to find out details about how certain things work, as opposed to duplicating the info in the docs and risking out-of-sync docs. The Truth Is In The Code - it just has to be expressed in an understandable way, which also helps code quality. For example (no offense to the writer of course), the table of reference properties at [2] is risky, as it has to be maintained in parallel with the code. I'd rather link to a javadoc page which lists those parameters, or better, directly to the code where the parameters are defined in a readable way, which cannot be out of sync (link using slingdoc tags described below). [2] http://incubator.apache.org/sling/site/servlet-resolution.html A technique that I've found useful to avoid duplicating info is to tag code sections as belonging to the explanation of some aspect of our software. For example if we have a document that explains how scripts are resolved, we'd tell people to lookup code for the slingdoc.script.resolution tag, and include this tag in comments where appropriate. This requires people to read code, but we're talking to developers, aren't we? And Google is our friend if those tags are sufficiently unique. Also, to document dynamic things that are hard to lookup in code, let's add more useful logging messages where needed, and refer people to those for details. Or improve something like the SLING-3 RequestProgressTracker, so that people can find by themselves exactly how Sling handled a particular request, without risking complicated explanations in the docs. That effort has much more long-term impact than writing docs. 3) Apart from the overview and general principles, things are best explained by examples. The best examples are live ones, that people can play with immediately and that never go out of sync with the code because they *are* code. Or, as in the Lucene book, readable automated tests, even if they don't improve the test coverage but are here only as examples. So I'd stay a little vague on purpose in descriptive docs, to lessen the risk of info rot, and refer people to working examples for details. In conclusion, the key requirement is not writing docs, it is "developer usability" as we might call it. We need to explain and demonstrate Sling to developers, but IMHO the fewer lines of documentation the better. If we agree on these principles, I'll add them to our website to explain how we see things, and help us keep the right focus. WDYT? -Bertrand
