[Bese-devel] Re: ucw documentation effort

[Adam Jones]

On 12/1/05, Maciek Pasternacki <maciekp at japhy.fnord.org> wrote:
> On Pungenday, The Aftermath 21, 3171 YOLD, Adam Jones wrote:
>
> > Looking at the documentation provided from the source code I was
> > thinking that a decent place to start a reference would be to
> > restructure the current source documentation into a one page per
> > function/macro/class/(computational object just to have a generic term
> > for everything involved). From there the next step I see would be to
> > add descriptions for it and provide a facility for user comments. Yes,
> > this is almost exactly like the PHP documentation system, but that
> > works really well and I think it would be good here.
>
> Maybe some auto-docstring-to-wiki?

That is pretty much what I was thinking. The problem there is
versioning. If version X of ucw comes out which comments are valid? A
good workaround for problem foo is awesome to have right there in the
wiki, up until problem foo actually gets solved in the code, then it
is just confusing. I think the answer would be to have people
categorize things as general tips vs workarounds. That said then
someone has to evaluate every workaround with a new version ... which
feels like busywork.

It would be neat to see some kind of capacity to link wiki comments to
a bug database, allowing now-invalid comments to be marked so when a
bug is fixed. Seems like something too big for this kind of project
though.