Comments in configuration files

Rahul Sundaram sundaram at redhat.com
Thu Jan 5 19:58:00 UTC 2006


Stuart Ellis wrote:

>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.
>  
>
(CCing fedora-devel list)
Might patch these as appropriate and send these upstream as required if 
agreed upon as a general policy.




More information about the docs mailing list