documentation effort

[Khaled Daham]

> I've been researching documentation mediums, and looked seriously at
> several.  My goals in a format are:
> + it be easy to use without having to learn very much
> + that the tools to render it be widely available
> + that it support rendering the docs to html, text, pdf, and perhaps texinfo
> + that the output look good in every format
> + that the features be complete (for our purposes), but be small enough
> that two different authors expressing the same ideas will do it the same
> way.
> 
> I considered DocBook, html, plain text, (hyper)latex, cweb, linuxdoc,
> debiandoc, roff, and handrolling an SGML scheme.  Being completely
> objective, debiandoc won me over.  All the others failed at least one of
> the above criteria.

How did DocBook fail one of the above criteria ?
IMHO DocBook is the most generic and complete set that someone can pick up
regardless of OS preference, packages exists etc.

> debiandoc requires perl (and a few perl modules), Jim Clark's 'sp', tex,
> and the DTD file.  In Debian, the package is debiandoc-sgml.

Which make it less attractive for those not doing Debian.

> So, what docs do we need?  I've started ``About FreeRADIUS'' (project
> information (lists, cvs, etc), feature lists) and ``FreeRADIUS Operating
> Manual'' (config files how and why, modules and their features, trouble-
> shooting guide).  I'd like to replace all the files in the doc/ dir, even-
> tually.

Maybe something like how PostgreSQL have divided the docs.

Tutorial <- simple a-couple-of-brain-dead steps to have it running
Admin <- more in-depth explaining.
Developer <- explaining the module setup and inner stuff.

> Offer skeleton tables-of-contents, as to how you think some documentation
> should be structured.
> 
> Where should the docs go?  In the radiusd module, too?  In its own module?

Why not just keep it in doc/ ?

/Khaled Daham, w.arts
Mail:    khaled@w-arts.com, khaled@telia.net
Cell:    +46-70-6785492
FreeBSD: The Power to Serve! http://www.FreeBSD.org/