Date: Sun, 15 Apr 2001 16:17:12 -0700 From: Bengt Richter <bokr@accessone.com> To: Dima Dorfman <dima@unixfreak.org> Cc: freebsd-doc@freebsd.org Subject: Re: Suggested adendum to FAQ section 3.22 Message-ID: <5.0.2.1.1.20010415154814.00ac3830@mail.accessone.com> In-Reply-To: <20010415193643.3E84A3E2F@bazooka.unixfreak.org> References: <3AD6B215.189906@ludd.luth.se>
next in thread | previous in thread | raw e-mail | index | archive | help
At 12:36 2001-04-15 -0700, you wrote: >Joachim =?iso-8859-1?Q?Str=F6mbergson?= <watchman@ludd.luth.se> writes: > > Problem discussion: [...] I understand where you're coming from with this, but I don't think >it's appropriate to try to document every possible mode of failure. >That's sort of like documenting the fact that the network cable must >be plugged in in order for this stuff to work! If we did that, we'd >be too busy changing all of the questions with the latest way to break >the system instead of writing new and more useful documents. > >The answer attempts to describe the most common solution to the stated >problem as derived from reading -questions. It can't possibly mention >every single thing that could go wrong, and mentioning just some of >the more obscure things isn't going to help anything. I understand >that it might help a few other people, but I simply don't think it's >worth it. My preference as a documentation consumer is to have separately placed info for my three most common types of access: (1) quick reference, best satisfied with cookbook examples of the two or three most common usage patterns, followed by concise explanations in case I don't immediately see what I needed; the best man pages do this, (2) looking for something normal, but more obscure, needing a complete exposition of normal usage, with minimal error info; again the best man pages do this, and (3) troubleshooting mode, where the subject is not normal operation, but exceptions, and looking for a clue as to what happened. This is the kind of material you are talking about, right? As with programs, perhaps documentation can benefit by moving exception stuff out of the way of the normal stuff? (1) is why I like reference cards that fit in your shirt pocket, or equiv. (2) is why I like non-tutorial, concise, well-indexed, orderly manuals, especially the slim-volume types. (3) could be a separate document, a well-indexed collection of pitfall descriptions. Even a file of (long) one-liners that could be grepped for pitfall avoidance hints could be useful. People could add a line whenever they fell into something unpleasant. (4) (added right here before your eyes) is the tutorial intro and exercises category. oops, gotta run... Regards, Bengt Richter To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?5.0.2.1.1.20010415154814.00ac3830>