Hi, I think we need to improve the way we update the documentation. Right now I see several issues are marked as closed even though we haven't documented them. Typical examples include new macros. They should be documented on xwiki.org before we close the issue IMO. At the very least if for some good reason we cannot do it immediately at least a new issue for documenting them should be created at the same time so that it's not forgotten and so that it's implemented in the future. Nobody likes documenting stuff so my belief is that someone who does something must do it completely, i.e. design, implement, *document* and support. WDYT? Thanks -Vincent ___________________________________________________________________________ D�couvrez une nouvelle fa�on d'obtenir des r�ponses � toutes vos questions ! Profitez des connaissances, des opinions et des exp�riences des internautes sur Yahoo! Questions/R�ponses http://fr.answers.yahoo.com
Dear Vincent, On 1/6/07, Vincent Massol <[email protected]> wrote:
Hi,
I think we need to improve the way we update the documentation. Right now I see several issues are marked as closed even though we haven't documented them. Typical examples include new macros. They should be documented on xwiki.org before we close the issue IMO. At the very least if for some good reason we cannot do it immediately at least a new issue for documenting them should be created at the same time so that it's not forgotten and so that it's implemented in the future.
Nobody likes documenting stuff Even if it might sound strange, I do like to document stuff, and I was doing this on the previous projects I worked on together with Marta and Sergiu. However, I can only help with this starting this spring.
so my belief is that someone who does something must do it completely, i.e. design, implement, *document* and support. This is a good idea no matter whether there is somebody working only on the documentation or not. Then that person can focus on writing good user manuals and tutorials, rather than spending inordinate amounts of time trying to understand all parameters of every obscure macro.
WDYT? I think that the APIs should be documented by the implementers since they have the most knowledge on how these things work internally.
Best Regards, Catalin Hritcu
Hi Catalin,
-----Original Message----- From: Catalin Hritcu [mailto:[email protected]] Sent: samedi 6 janvier 2007 13:20 To: [email protected] Subject: Re: [xwiki-dev] Documentation and issue closing
Dear Vincent,
On 1/6/07, Vincent Massol <[email protected]> wrote:
Hi,
I think we need to improve the way we update the documentation. Right now I see several issues are marked as closed even though we haven't documented them. Typical examples include new macros. They should be documented on xwiki.org before we close the issue IMO. At the very least if for some good reason we cannot do it immediately at least a new issue for documenting them should be created at the same time so that it's not forgotten and so that it's implemented in the future.
Nobody likes documenting stuff Even if it might sound strange, I do like to document stuff, and I was doing this on the previous projects I worked on together with Marta and Sergiu. However, I can only help with this starting this spring.
Ok that's good to know, thanks! Yes any help is good and it's true that lots of XWiki users can help on the documentation. The fact that our documentation is on a wiki is for this purpose actually ;-) I think one good idea would be to at least have documentation issues in JIRA so that we can regularly send an extract of all doc needs to the user and dev list and ask for help.
so my belief is that someone who does something must do it completely, i.e. design, implement, *document* and support. This is a good idea no matter whether there is somebody working only on the documentation or not. Then that person can focus on writing good user manuals and tutorials, rather than spending inordinate amounts of time trying to understand all parameters of every obscure macro.
WDYT? I think that the APIs should be documented by the implementers since they have the most knowledge on how these things work internally.
Thanks -Vincent ___________________________________________________________________________ Yahoo! Mail r�invente le mail ! D�couvrez le nouveau Yahoo! Mail et son interface r�volutionnaire. http://fr.mail.yahoo.com
On Saturday 06 January 2007 06:41, Vincent Massol wrote:
Hi,
I think we need to improve the way we update the documentation. Right now I see several issues are marked as closed even though we haven't documented them. Typical examples include new macros. They should be documented on xwiki.org before we close the issue IMO. At the very least if for some good reason we cannot do it immediately at least a new issue for documenting them should be created at the same time so that it's not forgotten and so that it's implemented in the future.
Nobody likes documenting stuff so my belief is that someone who does something must do it completely, i.e. design, implement, *document* and support.
WDYT?
Excellent idea. I'd like to see some explanations in the javadoc as well. Is there already some guidelines about documenting code and project (I mean tutorial, dev guide, the web site content)?
participants (3)
-
Catalin Hritcu -
Marc Lijour -
Vincent Massol