[Discuss] tips doc from andy oram

[adam hyde]

hey,

Recently I have been in contact with Andy Oram - he's an editor at
OReilly and is their expert on online documentation
(http://radar.oreilly.com/andyo/). He's a really nice guy, and its great
to be in touch with him as he knows a lot about this area.

Anyways, it was nice to hear (actually i was a bit shocked) that he
thought floss manuals was a step further than most documentation
projects he has seen (!)...I mean, I always knew it ;) but to hear it
from someone who knows this area so well is pretty cool.

The other thing is that he very generously sent a one page guide on
writing documentation. He said we can use it if we credit him. I was
thinking we could link it from the repository home page under "GUIDES".
Its juts a short text but I think its useful for those writers that
might come to contribute and need some help working out what writing
good docs is all about :

==================
A common problem is to jump into an description of "what to do"
without saying "why" or "how it works." There's a kind of standard way
to introduce topics, which I'd like you to keep in mind (without
applyng it mechanically).

First you state a problem. Something is hard to do, or inefficient, or
requires contortions of some kind that may be unportable or
unmaintainable. This description is a motivator -- either the reader
knows he'll encounter the problem, or he can skip the chapter.

Then you summarize the solution, in the form of the software or
technique you're about to introduce.

It's often useful (if the technique is complicated or depends on
mysterious hidden activities) to describe also the process that the
software goes through to carry out what the reader wants.

The writer's goal in all these "background" sections is to lay out for
the readers where you're taking them. You can call it setting the
stage or use some other metaphor. The idea, basically, is that you're
saying, "Here's where I'm going. Want to come along? Good, then let's
start."

Finally, you can get down to a blow-by-blow or line-by-line
description of what to do.

A good writer remembers the expected knowledge of his or her readers
and fills in the necessary background. One of the more
creative/intuitive parts of technical writing is deciding what
background you should introduce first, before getting to the
line-by-line description, and what background should be slipped in
along with the description. You want the initial background section to
flow well, to stay at a consistent level of detail (otherwise, people
will say "Why did you tell me so much about X and not Y?"), and to
make the readers understand the technology in general. Some background
is too narrow to be included in the background section; for instance,
if there's some dumb work-around you need for a design flaw, you can
leave that till you get to it in the line-by-line description.
=======================================

He also wrote a much more extended doc:
http://praxagora.com/andyo/professional/reliable.html

I was wondered what you all thought about his comments on doc writing?
Also, any thoughts on the appropriateness of the page he offered for
guide section? 

adam



-- 


adam hyde
floss manuals

free manuals for free software
http://www.flossmanuals.net

mobile : + 31 6 154 22770 (Netherlands mobile)
email : adam at flossmanuals.net