Re: [Gnumed-devel] GNUmed website

[Hilmar Berger]

On Mon, 15 Dec 2003 15:56:32 +1100
Ian Haywood <address@hidden> wrote:

> The people at Wikibooks.org are likely to come up with a solution
> at some point [probably long before we have a user's manual longer than 10 
> pages]
> 
> In the meantime. I think  the advantages
> outweigh this problem, as the docs need to be able to evolve quickly and have 
> numerous people work on them. Certainly for the developer's manual we
  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Well, I don't know if a wiki is what we need now or not. It might be a good 
idea to make accessing and changing the documentation easier. I know that 
changing SGML files is not an easy task. I tried to maintain the manuals as 
well as I could, but never felt very comfortable converting plain text to SGML. 
However, I feel that the main problem was not that it was too difficult to 
change the manuals. It's just that there was almost no input to the manuals at 
all, that is, almost nobody was willing to write as much as plain text that I 
could include in the manuals. 
As we discussed on gnumed.de, writing documentation should be based on a 
thourough understanding of the concepts and their implementation. So what we 
really need is 
- somebody really reading the manual and identifying missing concepts and 
missing descriptions of their implementation
- developers writing documentation of at least the concepts the used in their 
code (important concepts first)
- somebody (me) extracting the current python docstrings from the modules. 
PySource from the docutils site seems to be the tool we need for this. 

We shouldn't talk too much about the tools we would like to use, but 
concentrate in creating content.
IMHO dropping text/whatever files in some directory of the CVS would be 
sufficient for the beginning.
I'm willing to continue integrating plain text into the current 
docbook-SGML-file if that is wanted. 

Hilmar