forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ross Gardler <rgard...@apache.org>
Subject Re: Creating documentation (Re: Link to CSS howto-structurer-dsl.html)
Date Sun, 18 Dec 2005 13:25:33 GMT
David Crossley wrote:
> Ross Gardler wrote:
> 
>>(this is a general comment not at all aimed at the authors of these 
>>mails - since I'm in that group)
>>
>>Why is it that people take the time to write clear documentation like 
>>this but nobody puts it into a document?
>>
>>Someone, please get this into documentation within the structurer 
>>plugin.
> 
> 
> Even if it is just a placeholder <fixme> note that has a link
> to the mail thread. If one cannot manage that, then add a Jira
> issue (which would perhaps take more effort).
> 
> 
>>Note that it need not be the person who posts the solution, 
>>maybe the person asking the question could help too.
>>
>>(remember this is *not* aimed at people in this thread, it's a general 
>>point that I often wonder about).
> 
> 
> Perhaps we should each ask ourselves that question.
> 
> For me, i used to have good documentation contribution
> habits, which have slipped. This is what got me joined
> to the Cocoon community. When i answered a technical
> question then i would do it by adding to the relevant
> documentation, then copying that for the email. Sometimes
> the other way around. Follow up with tweaks, then send
> the patch.
> 
> Why did the habit slip? Became too busy i suppose.
> More likely forgot the benefit.

Yes, I am in that very same camp (my first contribution in Forrest was 
collating what I learnt from the mail lists).

In my commercial work I insist on all support answers including an URL 
to our documentation. Of course, sometimes the docs don't adequately 
cover the question asked, so the support engineer has to write a doc 
then write the email (which may contain a more specific example). The 
docs are in a CMS system (Daisy in our case) and so the act of writing 
the docs is easy.

I raise this because I have found it works really well. It only adds a 
few seconds to the responds time for support questions and our docs are 
growing daily.

[ASIDE:

I intend to extend the CMS so that it also acts as a mail archive and 
that links in the mail archives will be re-written to point to the 
internal documentation. But that's a different story.
]


> That is actually silly because that technique, of answering
> a question by going to a bit more effort, is a huge
> community-builder. Consider the multiplication factors.
> If each of us did a little, then our improved documentation
> would mean no need for repeat questions and we can move on.

Yes, this is exactly what we are finding. Because *every* mail to our 
support list has a link to our docs we are finding more people are able 
to find what they need in the docs - the support archives provide 
additional context.

> If people ask the question again, then we can just
> provide the URL or copy the text.

Hehe - I was replying as I read, but I won't bother deleting as I 
usually do, it is interesting we arrived at exactly the same point.

I am going to build on this theme in my reply to Richards mail regarding 
a wiki.

Ross

Mime
View raw message