On Jan 19, 2008 4:14 PM, Peter Svensson <[EMAIL PROTECTED]> wrote: > ...What I would like to be provided with is something like this...
You doc plan below makes sense - getting some up-to-date "getting started" docs is next on my plate once SLING-149 is over. One thing that's important in docs is to make sure we can keep them up-to-date over time. In my view, the following basic principles help for this: 0) Create as little documentation as possible. But not less that what's needed to make things understandable ;-) 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 refer people to (readable) code to find out details about how certain things work, as opposed to duplicating the logic in the docs and risking out-of-sync 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. Also, as Sling can be used in *very* different ways depending on people's needs, I think we'll need some docs along the lines of "here's an example Sling app based mostly on client-side javascript code", or "here's an example Sling app based mostly on server-side Java code", etc.. We'll of course have our favorite way of doing things, but if community members are using Sling in different ways it'd be good to reflect this in such examples. And lastly, magazine articles are a good way of getting our message out to more people, so I wouldn't mind people writing magazine articles about Sling instead of (or in addition to) contributing docs here. Right now, IMHO the most urgent doc needs are "Sling basic principles - how does Sling process requests" and "getting started with the Sling Launchpad using ESP scripts". I hope to help create those soon, but as I said I have to get rid of SLING-149 first. Peter, does the above help you find out how you can help? -Bertrand >... 1. Quick start to develop with Sling > 1.a Installation > 1.b Check that things work > 1.c Mount as webDAV (in windows and Linux) > 1.d Most important facts about Sling resources. Where the monsters are and > how to defy them. > > 2. Examples on how to access Sling resources from client > 2.a From Ajax-clients in browser > 2.b From Java programs > > 3. Examples on how to write Sling server-side scripts > 3.a What kind of resources can be used in scripts > 3.b Simple example in Rhino > 3.c Simple example in Erb > 3.d Simple example in Jsp > > 4. etc...
