On May 30, 2008 at 14:05, Martin Hoffmann <[EMAIL PROTECTED]> wrote: > Heisann, > > as you may have noticed, I am playing around with documentation lately. > In the process I have tried many things: TeX, Docbook, various Wikis. > In the end, I am afraid that short of writing something new (which I > did, too, but that is a different matter), Docbook turns out to be the > best system. While editing XML is quite horrible, the advantage of the > tool base around it makes up for a lot. As prove, I have taken bits from > the existing docbook for the auth module and crafted a man page for > it:[0] > > http://www.partim.de/pub/misc/auth.7
It looks very nice! (I love man pages) > > I for one find having a manual page the perfect documentation. But of > course, you can turn this into HTML or PDF or whatever. > > So, since the Drupal approach and the Wiki approach didn't exactly > attract a horde of interested documenters, I think we are back to a > small core team. I browsed around a bit and it appears that the standard > way of doing documentation is providing a normal manual and having a > version online where users can put comments into pages (Blog style). > > So, unless anyone objects, I would like to start yet another attempt at > the SER User Manual. I would like to store the sources in the SER > repository, in doc/user_manual. For module documentation, I'd like to > keep a file reference.xml containing a single <refentry> for the module > in each module directory and ditch the old doc subdirectory. So you want to move all the *.xml in modules/*/doc into this new directory doc/user_manual? I liked it when it was in the same place as the module (I could do 1 commit for both a code an doc chage), but that's really something very minor. Another point would be loosing history (if we move only the xml files and not the whole doc dirs). OTOH I think that at least right now the history for docs has little value (is not like we need to see why some change happen in the docs very often :-)). > > I have no idea what would be a good tool to allow the online version > with comments. I suppose Greger would suggest Drupal. Is that hard to > set up? Are there any other suggestions? As the place, I would like to > have http://docs.sip-router.org/user-manual/. > > I am all to aware, that I am arguing against my own earlier opinion. > But, it appears even I can learn ;) > > All earlier volunteers are invited to join. If you have any material, > that you would like to see included in the user manual, let me know > and/or send it to me. > As far as I'm concerned I agree with anything that might bring us more documentation and it looks like your approach would :-) But my opinion doesn't really matter much when docs are involved (I haven't done any doc system testing like many of you have, I haven't written much docs and I'm more like the .txt or tex kind of guy anyway). Andrei _______________________________________________ Serdev mailing list [email protected] http://lists.iptel.org/mailman/listinfo/serdev
