I think this sounds very reasonable. I hope to be able to contribute as soon as I understand more and start doing some good work :)
Cheers, PS On Feb 19, 2008 9:34 AM, Bertrand Delacretaz <[EMAIL PROTECTED]> wrote: > (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 >
