Comments in configuration files

[Stuart Ellis]

On Thu, 2006-01-05 at 18:47 +0530, Rahul Sundaram wrote:
> Hi
> 
> It seems that several configuration files in Fedora does not include 
> helpful comments as necessary to guide users on where to look for 
> information or which formats to follow.  The crontab files could have a 
> initial commented line specifying the format or hosts file could refer 
> people to its man page for examples. Would the documentation team be 
> willing to file bug reports with comments/content as appropriate?
> 
> Do we need such guidelines as inclusion/release criteria?

I think that it would be a good policy for those configuration files
that are written by Red Hat or Fedora developers
(e.g. /etc/sysconfig/*, /etc/httpd/conf.d/*), even if it's just a bit of
boilerplate text that identifies the file as a custom item and provides
a reference for more information.

Where configuration files are supplied by upstream as part of the
software, it may be that tweaking them would be felt to be against the
general use-upstream-defaults policy. That's probably something that
would need discussion on development or maintainer lists to work out.

-- 

Stuart Ellis

stuart at elsn.org

Fedora Documentation Project: http://fedora.redhat.com/projects/docs/

GPG key ID: 7098ABEA
GPG key fingerprint: 68B0 E291 FB19 C845 E60E  9569 292E E365 7098 ABEA
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
URL: <http://listman.redhat.com/archives/fedora-docs-list/attachments/20060105/23e6f176/attachment.sig>