On Wednesday, July 10, 2002, at 07:50 AM, Nicola Ken Barozzi wrote:
Diana, there is a need for docs on error generation. Where do I start?
There are many ways to start.
A few ideas: 1. Ok, let's say you're totally pressed for time. A simple approach is to write a few FAQs. Anticipate the kinds of basic questions people might ask (as did Michael). Do your best to answer them, even if you don't have time to delve into a lot of example or conceptual detail. Users will appreciate the effort, no matter how preliminary. Many times, user can then continue on their own with these basic hints.
2. Let's say you just need to quickly illustrate how something is done. Author a Snippet: simple overview (what it is), code, short explanation. Write a FAQ that points to the Snippet.
3. Ok, you have more time and more info to share. Write a How-To. Give concise instructions, but with a bit more detail. Again, make sure an FAQ points to it.
4. Write a core doc. If no decent models/templates exist, follow these simple
very tentative suggestions. Sometimes, if you have created any of the above
three docs already, you can incorporate (or link to them) in this "core" doc.
a. Warn readers if you are writing about non-release topic. Throughout,
point out differences between release and HEAD branches, as appropriate.
b. Write a short overview. Give readers some idea what the doc is about.
c. Advise readers if they need to know other concepts before reading the doc.
Point them to any available background reading if it's available.
d. Start by providing some conceptual info first. Be careful not to provide
too much implementation detail before you've explained the principal ideas, either
through concepts or examples. IMHO, this is the main difference between
a how-to and a core doc: the amount of conceptual detail and examples.
e. Provide a simple example, explain it, and then provide a more complex,
real-world example. Users complain the doc examples are too trivial.
If it's easier, point to a few Snippets you may have already written.
f. Anticipate user problems or questions. Add tips, if necessary.
g. Summarize your doc. This gives you a chance to convey the main points
in a slight different way, to reinforce what's important to the reader.
Anyone care to comment on this rough sketch?
(me lazy on docs and Andy Oliver kicks my butt for this ;-)
Thanks Andy ;-) and thanks Ken!
-- Diana
