Re: Why I hate "info"

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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


[Index of Archives]     [Current Fedora Users]     [Fedora Desktop]     [Fedora SELinux]     [Yosemite News]     [Yosemite Photos]     [KDE Users]     [Fedora Tools]     [Fedora Docs]

  Powered by Linux