[Serdev] Thoughts on Documentation -- Again

[Jan Janak]

Martin,

I am fine with this, I wrote a lot of documentation in XML-based docbook
in the past. I am not sure what is the best way to add support for
comments in documents rendered as HTML, but I would start asking google.

Regarding the sip-router.org site, you should have access to it so feel
free to do necessary changes there.

  Jan.

Martin Hoffmann 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
> 
> 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
> Serdev at lists.iptel.org
> http://lists.iptel.org/mailman/listinfo/serdev