You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@sling.apache.org by Bertrand Delacretaz <bd...@apache.org> on 2008/01/21 10:22:36 UTC
Documentation plan (was: esp script not parsing)
On Jan 19, 2008 4:14 PM, Peter Svensson <ps...@gmail.com> 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...
Re: Documentation plan (was: esp script not parsing)
Posted by Peter Svensson <ps...@gmail.com>.
I don't have a working printer at home, but I'll do it tomorrow when I'm at
a client.
Cheers,
PS
On Jan 21, 2008 10:47 AM, Bertrand Delacretaz <bd...@apache.org>
wrote:
> On Jan 21, 2008 10:27 AM, Peter Svensson <ps...@gmail.com> wrote:
>
> > ...Is there some kind of publicly accessible SLing server that can be
> used for
> > writing 'live' documentation?...
>
> Our wiki is at http://cwiki.apache.org/confluence/display/SLING/wiki -
> but writing to it requires an account.
>
> In my opinion, the Sling PPMC (which is our "governing body" - the
> people listed at
> http://incubator.apache.org/sling/site/project-team.html) could vote
> to give you write access to the wiki, but you'd need to send a
> Contributor License Agreement to the ASF (aka "CLA", see
> http://www.apache.org/licenses/).
>
> What do people think? We might have other community members
> interesting in helping with the docs over time, so it'd be good to
> have a simple policy for giving them write access to the wiki.
>
> -Bertrand
>
Re: Documentation plan (was: esp script not parsing)
Posted by "Padraic I. Hannon" <pi...@wasabicowboy.com>.
+1 here as well.
-paddy
Re: Documentation plan (was: esp script not parsing)
Posted by Felix Meschberger <fm...@gmail.com>.
Hi,
Am Montag, den 21.01.2008, 10:47 +0100 schrieb Bertrand Delacretaz:
> On Jan 21, 2008 10:27 AM, Peter Svensson <ps...@gmail.com> wrote:
>
> > ...Is there some kind of publicly accessible SLing server that can be used for
> > writing 'live' documentation?...
>
> Our wiki is at http://cwiki.apache.org/confluence/display/SLING/wiki -
> but writing to it requires an account.
>
> In my opinion, the Sling PPMC (which is our "governing body" - the
> people listed at
> http://incubator.apache.org/sling/site/project-team.html) could vote
> to give you write access to the wiki, but you'd need to send a
> Contributor License Agreement to the ASF (aka "CLA", see
> http://www.apache.org/licenses/).
>
> What do people think? We might have other community members
> interesting in helping with the docs over time, so it'd be good to
> have a simple policy for giving them write access to the wiki.
+1
Regards
Felix
Re: Documentation plan (was: esp script not parsing)
Posted by Bertrand Delacretaz <bd...@apache.org>.
On Jan 21, 2008 10:27 AM, Peter Svensson <ps...@gmail.com> wrote:
> ...Is there some kind of publicly accessible SLing server that can be used for
> writing 'live' documentation?...
Our wiki is at http://cwiki.apache.org/confluence/display/SLING/wiki -
but writing to it requires an account.
In my opinion, the Sling PPMC (which is our "governing body" - the
people listed at
http://incubator.apache.org/sling/site/project-team.html) could vote
to give you write access to the wiki, but you'd need to send a
Contributor License Agreement to the ASF (aka "CLA", see
http://www.apache.org/licenses/).
What do people think? We might have other community members
interesting in helping with the docs over time, so it'd be good to
have a simple policy for giving them write access to the wiki.
-Bertrand
Re: Documentation plan (was: esp script not parsing)
Posted by Peter Svensson <ps...@gmail.com>.
Yes, I think so. Now I only need to understand how things work so I can
write about them :)
I like the idea to have small, concise documents targeting one thing at a
time - ideally visible on the screen without scrolling.
Is there some kind of publicly accessible SLing server that can be used for
writing 'live' documentation?
Cheers,
PS
On Jan 21, 2008 10:22 AM, Bertrand Delacretaz <bd...@apache.org>
wrote:
> On Jan 19, 2008 4:14 PM, Peter Svensson <ps...@gmail.com> 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...
>