On Thu, 2006-01-05 at 11:25 -0600, Tommy Reynolds wrote: > Uttered Rahul Sundaram <sundaram@xxxxxxxxxx>, spake thus: > > > 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. > > Under FCn, most configuration files have system-config-* tools, or > similar, to allow newbies to painlessly access these files. A user > sufficiently advanced to attack the raw files had better have enough > savy to know the file formats, or at least where to find them. If > someone doesn't know they can "man fstab", is that a person who > _should_ be editing "/etc/fstab"? Not on my machines, they won't. > > OTOH, I do describe the crontab field order using an embedded > comment but any more, such as trying to explain valid entries, giving > examples and the like do not belong here. > > Also, some tools rewrite config files and do not preserve comments. > Frustration ensues. > > So my position is this: "no" to newbie comments in the files > themselves, but "yes" to a cut-n-paste header comment in the man(1) > page. I'm with you up to the last paragraph, and my only caveat there isthat I don't like the idea of messing with canonical man pages, which are duplicated so often across the net. I think this need should be filled by documents like the Administration Guide[1]. This seems like an issue for that drafting process, IMHO. [1]http://fedoraproject.org/wiki/Docs/Drafts/AdministrationGuide -- Paul W. Frields, RHCE http://paul.frields.org/ gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717 Fedora Documentation Project: http://fedora.redhat.com/projects/docs/
Attachment:
signature.asc
Description: This is a digitally signed message part
-- fedora-docs-list@xxxxxxxxxx To unsubscribe: https://www.redhat.com/mailman/listinfo/fedora-docs-list
