Re: [PROPOSAL] Extending Sitemap Error Handling

[Diana Shannon <sh...@apache.org>]

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