New subject: [xwiki-users] [Strategy] Improving the documentation, giving shorter answers to email questions...

26 May 2008

Hi everyone,

Here's a strategy that I try to follow and that I think might be good  
that we all follow. The end goal is to improve the XWiki documentation  
on xwiki.org.

Here's how it goes:

1) someone (A) asks a question on a xwiki list
2) someone (B) knows the answer
3) B verifies that the answer can be found on xwiki.org and if so  
gives a link to it in the reply to A
4) If the answer is not found on xwiki.org, then B adds it (*) and  
then gives a link to it in the reply to A

In this manner we'll all enrich the xwiki documentation and it'll only  
take marginally longer to answer questions. The next time someone asks  
the question again we can simply point him/her to the location on  
xwiki.org

What happens now is that usually people answer in the email, often  
giving very long and elaborate answers with lots of knowledge/wisdom  
in it. Then another person comes in, asks the same question and we  
answer again, etc. The result is:
* the xwiki.org documentation is not better
* overall as a team we are less efficient

(*) One difficult in putting the answer on xwiki.org is to find the  
right location where to put it. So here are a few tips:
* For code snippets, add it to the Code Zone
* For questions on how to use XWiki, please add it to the Features guide
* For development questions, add it to the Developer's guide
* For configuration questions and administration questions, add it to  
the Administration guide
* For other questions, add them to the FAQ

Applying my own strategy, you can find the content of this email at
http://tinyurl.com/4xfel2 
  :)

Let me know what you think!

Thanks
-Vincent