On Sun, Nov 12, 2006 at 05:31:56PM +0000, Timothy Murphy wrote: > <flame> > Am I alone in thinking that the info program > encourages bad documentation? > > If only people writing documentation > would consider for a moment why people want to use their program. > To my mind, if 90% of users are interested in one application, > then that should be the subject of the documentation, > with other uses relegated to separate chapters or an appendix. > > Also a simple example of usage > (using script or a similar capture program) > is worth a ream of metadata. > It is usually perfectly obvious how to modify an example > to suit one's particular case, while something like > squiggle [options] <io> <xpd> > takes an age to decipher. I find it interesting that most of the people who commented on this did so on the info vs man issue. I think the more substantive issue is that of bad documentation, regardless of presentation. A few observations, then. I do not wish to excuse the sins of documentation, merely explain why I think they occur so often and offer some comments on how to avoid them. * Most programmers are neither writers nor technical writers. Their C or Python is far better than their English. People who can do both are rare. * Technical writers are not programmers, and programmers and managers must not expect them to be. * Many projects put far more resources into developing code than into documentation, either internal or external. I think this is a mistake, but they don't ask me. If your internal documentation (functional spec, function call descriptions, etc.) is properly done, the techical writer can write from that, a relief to both the programmers and the writers. Also, the final product is less likely to be buggy and more likely to come in on time. * I agree with you that lots of examples are a good idea. They are harder to write and maintain than straight prose. * Procedural documentation is preferable to item documentation. By procedural documentation, I mean, how to do things the user is likely to want to do. In your case, how to resize a partition: first, go find a virgin. Second, umount the partition. Then shrink the file system. Only then do you resize the partition. Now offer the virgin to Murphy. Finally, mount the partition, not the virgin. By item documentation, I mean, "This is the resize button. Use it to resize your partition." To which the appropriate response is, "No shit, Sherlock". * Finally (this is a management issue, not a documentation issue), get and heed feedback from the users. -- Charles Curley /"\ ASCII Ribbon Campaign Looking for fine software \ / Respect for open standards and/or writing? X No HTML/RTF in email http://www.charlescurley.com / \ No M$ Word docs in email Key fingerprint = CE5C 6645 A45A 64E4 94C0 809C FFF6 4C48 4ECD DFDB
Attachment:
pgpdVAUleI6CU.pgp
Description: PGP signature
