21 Apr
2009
21 Apr
'09
11:11 a.m.
Jan Janak writes:
I certainly agree with the idea that all new stuff
should be
documented, but I wonder whether we should revisit the system we
write documentation in? I am personaly fine with docbook.
in k we want to keep the tradition that ALL modules are fully
documented. we don't accept a module or a new function in a module,
unless it is fully documented. the system that is used to write the
docs must be such that we can generate the doc at least as as txt and
html. we have made a huge effort to write the readmes as they currently
are. unless there is an automatic means to change their format, the
format cannot be changed, i.e., manual change is out of question.
regarding common modules, before this project is announced to public,
there thus needs to be k style documentation of all of them.
perhaps it was not a good idea to try to merge the modules after all if
also documentation style is different in k and s, because we need to
have two doc subdirs in all of them (one for k and another for s).
But if our goal is to produce plain text READMEs,
wouldn't it make
more sense to adopt something simpler, for example the dokuwiki
format? It is easily readable as plain-text and we can edit it in the
wiki and synchornize with
READMEs in the repository.
generation of web page readmes has to be automatic from the module doc
directory, since otherwise those two would never be in sync.
-- juha