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 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. 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. Best regards, Martin [0] Should you care, here are the sources: http://www.partim.de/pub/misc/auth-reference.xml _______________________________________________ Serdev mailing list [email protected] http://lists.iptel.org/mailman/listinfo/serdev
