[xwiki-dev] Documentation and issue closing

[Catalin Hritcu]

Dear Vincent,

On 1/6/07, Vincent Massol <vincent at massol.net> 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