Documentating the configuration files

[Karsten Wade]

On Fri, 2003-12-26 at 15:18, Jan Fabry wrote:
> Hello,
> 
> Are there any plans to documentate the configuration files, and their 
> relationship to each other? I know Fedora is a end-user-oriented 
> project, but for that one case when you need to change something for 
> which there is no GUI, it's not always easy to know where to start ("if 
> I want to add a directory to my path, where should I put it?").
> 
> The man pages alone don't always offer all the information you need: 
> configuration files can be very distro-specific, and might put the usual 
> configuration files in a totally different context.
> 
> If this doesn't fall under the scope of this project, I might start 
> something like this on my own, but of course it's always easier if we 
> work together.

This is an interesting idea.  It is reminiscent of the RHEL Reference
Guide
(http://www.redhat.com/docs/manuals/enterprise/RHEL-3-Manual/ref-guide/), which has many chapters devoted to config files.  Of course, something of that size and type _is_ out of scope for the Fedora docs project.

However, a very tight config file reference that was e.g. organized sets
of files done as multiple <variablelist> entries would be very useful,
even if such a reference work is outside of the FDP scope.

The real question is, how do you decide what exactly to document?

[root at erato etc]# find . -type f | wc -l
   1543

That's a whole bunch.  I would be concerned that no matter what number
and which files you chose to document, you would have a stand alone
document requiring regular manual maintenance, and which is somewhat
duplicating the effort of the man pages (deficient as they might be).

Another viewpoint would be to take the effort for doing this stand alone
reference and put that into updating the man pages.  An updated man page
should contain a complete list of all relevant config files, which then
may have their own man pages, and which should be self-documented inside
the config file itself (in comment blocks).  For *nix, this is the
proper place for documentation - comes loaded on the system and doesn't
require a separate reader and a network connection to access.  I'd
rather teach users to rely upon those resources, if it were all up to
me.

We've been contemplating for a while what such a project would be like. 
Huge.  That's about the size of it.  However, if the FDP group were to
take on this task, we might be able to get the Linux Doc Project to let
us convert all of the man pages to DocBook XML. ;-)

- Karsten, still dreaming large
-- 
Karsten Wade   :      Tech Writer, RHCE     :  o: +1.831.466.9664
kwade at redhat.com : http://rhea.redhat.com/ :   c: +1.831.818.9995
         Red Hat Applications : WAF, CMS, Portal Server         
-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --