[Gnumed-devel] Re: Gnumed documentation

[Jim Busser]

In reply to Sebastian, I also offer at bottom broader documentation 
thoughts. To the list could be added: extracted source code commenting 
(on which Hilmar just sent me something).

Sebastian - I have cc'd the list.. To bed now! Jim

On Mar 22, 2004, at 12:44 PM, Sebastian Hilbert wrote:
> Here is what I found re installation
> google search : Gnumed installation
> returns http://www.gnumed.org/development/installation/home.html
> -points to cvs which is hard to edit
> -should point to wiki
> -possible connection between wiki and sgml ?
>  <SNIPPED: more questions/ suggestions>
This is a good question - see my concerns below. I understand SGML can 
be a lot of work to have to manually maintain.

> - we need to get our own mailing-list re documentation
>  I will ask Horst if he lets us set up the list at his server
Maybe wait a bit to try Savannah's list manager a few more times.
I am not sure there is a rush - it's only a few people for now.
I am familiar with and like the mail.gnu.org/archive thus I
prefer we keep all lists there if we can. If Savannah remains
broken I wonder can a documentation subgroup make use
for now of the gnumed-announce list (not otherwise used)

> I propose we move the user-manual over to the wiki
Hilmar and Ian had been central to these, we should see what they think
> We then work on the above list . Does this make sense ?
Maybe I should not have snipped it, let us see though how much detail 
people want.
> Do we have to merge content before we move stuff
> Sorry I still have no idea how that wiki thing works
We can merge / move in either order but there is less to move if it is 
done after merging. There is also the need to coordinate, for example I 
disabled some of the old FAQs at Gnumed.org as part of putting the 
newer ones up. Karsten modified the roadmap on  the CVS as part of my 
having migrated it to the wiki. I would not want us to copy the manuals 
to a wiki without removing them (well, stubbing / pointing them to the 
wiki) from the CVS.

My broader thoughts:

I am conscious that Hilmar thought we need not worry about management 
tools, and just create content.

However I am hoping to integrate and update existing content, and I 
would like it to be easy to manipulate and re-deploy whether this be as 
wiki pages, html and/or pdf or other form suited to printing. With the 
small numbers of worker bees that we have, it cannot be a bad thing to 
identify & use tools that reduce work, if that it possible.

I am also thinking that once GNUMed is in actual use, it may be helpful 
to be able to call up context-sensitive help. Does any provision yet 
exist, or has been contemplated, in GNUMed for this purpose.

Various whitepapers at gnumed.net have been incorporated into the 
Developer manual but both contain dead links, and I worry in general 
how to watch for and to update these (or more important changes) 
especially when considering that multiple "source" and derivative 
documents may exist.

I wonder if there is an easy way by which we can create content on a 
wiki, and also specify various documents that are to be generated from 
various combinations of wiki pages, update-able either at 
pre-designated intervals and/or on demand. Is it useful to (and can 
anyone) recommend a particular wiki software from which it is known 
documents can most easily be created on an ongoing basis, perhaps in a 
scriptable fashion? I noticed Engelbert had contributed to MoinMoin a 
script at  http://moinmoin.wikiwikiweb.de/UtilityScripts

I came across and wondered of any use of the Lore Document Generation 
Framework "uses a limited subset of XHTML, together with some class 
attributes, as its source format which is viewable directly, so that 
even if Lore is not available the documentation is useful. It currently 
outputs LaTeX and HTML... The Twisted.lore Python package comes with 
every Twisted installation, works on Linux, Win32, Mac, supports Python 
2.1, 2.2, 2.3 alpha.
URL http://www.python.org/pycon/papers/lore-slides.html)