documentation dir

[Dimitrie O. Paun]

On September 18, 2002 04:10 am, Eric POUECH wrote:
> IMO, most of the documentation (even the internals description,
> status of DLL) should be made in the DocBook form

I don't think this is right. Documenetation that is meant for
the user should go into .sgml, no disagreement here. Documentation
that is meant for the ongoing developement of a DLL (something like
the TODO list, or a few comments on the internal structure, or
some tips, etc.) should go as plain text as close as possible to the
code that it's documenting.

I can not stress how important that is. I find this "developer"
documentation useful beyon words: as I read through the code, it 
gives me ideas on what to work, I keep it _updated_. On the other
hand, I've never even read 50% of the .sgml documentation even once.
But even if I do, it will never have the "current" status of the
one embedded in the/close to the code. As I said before, this thing
has been tried numerous times before, and everybody reached the
conclusion that the documentation pertaining to code should be
as close to the code that it's documenting (see javadoc et. Co.).

-- 
Dimi.