[Strategy] Improving the documentation, giving shorter answers to email questions...

classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

[Strategy] Improving the documentation, giving shorter answers to email questions...

vmassol
Administrator
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



_______________________________________________
users mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/users
Reply | Threaded
Open this post in threaded view
|

Re: [Strategy] Improving the documentation, giving shorter answers to email questions...

Shiva Shankar
Hi
This is excellent. Not being a Java programmer myself, this would be a great oppurtunity for contribution.
While we are at it, can we also plan to have a "manual" in say, PDF format? It would be great if a PDF manual can be generated (possibly automatically) from the contents of the documentation Wiki pages. Then it will be very useful for offline reference.
Shiva

PS: One of the best documentation for an Open Source project is Daisy CMS. Pretty much all that can be done using daisy, including administration, API, writing extensions etc is documented in the manual.
 
vmassol wrote
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



_______________________________________________
users mailing list
users@xwiki.org
http://lists.xwiki.org/mailman/listinfo/users
Reply | Threaded
Open this post in threaded view
|

Re: [Strategy] Improving the documentation, giving shorter answers to email questions...

Anupama11
In reply to this post by vmassol
Hi Vincent,
     It is a very good idea for improving both the documentation in
xwiki.org and the efficiency of answering Questions.

Regards,
project trainees.


> 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
>
>
>
> _______________________________________________
> users mailing list
> [hidden email]
> http://lists.xwiki.org/mailman/listinfo/users
>

_______________________________________________
users mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/users
Reply | Threaded
Open this post in threaded view
|

PDF Export for multiple pages (was Re: [Strategy] Improving the documentation, giving shorter answers to email questions...)

vmassol
Administrator
In reply to this post by Shiva Shankar
Hi Shiva,

On May 26, 2008, at 10:37 AM, shivshan wrote:

>
> Hi
> This is excellent. Not being a Java programmer myself, this would be  
> a great
> oppurtunity for contribution.
> While we are at it, can we also plan to have a "manual" in say, PDF  
> format?
> It would be great if a PDF manual can be generated (possibly  
> automatically)
> from the contents of the documentation Wiki pages. Then it will be  
> very
> useful for offline reference.

This is already possible. See
http://platform.xwiki.org/xwiki/bin/view/Features/Exports

Thanks
-Vincent

> Shiva
>
> PS: One of the best documentation for an Open Source project is
> http://www.daisycms.org/ Daisy CMS . Pretty much all that can be  
> done using
> daisy, including administration, API, writing extensions etc is  
> documented
> in the manual.
>
>
> vmassol wrote:
>>
>> 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
>>
>>
>>
>> _______________________________________________
>> users mailing list
>> [hidden email]
>> http://lists.xwiki.org/mailman/listinfo/users
>>
>>
>
> --
> View this message in context: http://www.nabble.com/-Strategy--Improving-the-documentation%2C-giving-shorter-answers-to-email-questions...-tp17467429p17467962.html
> Sent from the XWiki- Users mailing list archive at Nabble.com.
>
> _______________________________________________
> users mailing list
> [hidden email]
> http://lists.xwiki.org/mailman/listinfo/users

_______________________________________________
users mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/users
Reply | Threaded
Open this post in threaded view
|

Re: [Strategy] Improving the documentation, giving shorter answers to email questions...

FabienB
In reply to this post by Anupama11
This is a good idea especially if googling a question is able to direct us
directly into the xwiki doc.

Fabien

On Mon, May 26, 2008 at 10:39 AM, <[hidden email]> wrote:

> Hi Vincent,
>     It is a very good idea for improving both the documentation in
> xwiki.org and the efficiency of answering Questions.
>
> Regards,
> project trainees.
>
>
> > 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
> >
> >
> >
> > _______________________________________________
> > users mailing list
> > [hidden email]
> > http://lists.xwiki.org/mailman/listinfo/users
> >
>
> _______________________________________________
> users mailing list
> [hidden email]
> http://lists.xwiki.org/mailman/listinfo/users
>
_______________________________________________
users mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/users