cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Diana Shannon <>
Subject Re: [PROPOSAL] Extending Sitemap Error Handling
Date Wed, 10 Jul 2002 14:52:51 GMT

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 
very tentative suggestions. Sometimes, if you have created any of the 
three docs already, you can incorporate (or link to them) in this "core" 
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 
Point them to any available background reading if it's available.
d. Start by providing some conceptual info first. Be careful not to 
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

View raw message