the art^wcraft of writing (was: Re: [MPlayer-DOCS] CVS: main/DOCS/xml/en encoding-guide.xml, 1.36, 1.37)

[Diego Biurrun]

On Wed, Dec 28, 2005 at 01:58:28PM -0500, The Wanderer wrote:
> 
> Which makes it all the more impressive that you've managed to write the
> documentation sections you have on some of those subjects. As I said, I
> would have a devil of a time trying to write a good explanation even of
> something I understood in detail;

Maybe you should just give it a go.  (Good) writing skill is not
something that you are born with, pretty much like everything else it is
10% talent and 90% sweat.  Writing is often called an art, but this is
plain wrong, it's a craft.

I've given a presentation about writing (good) documentation at
LinuxTag, I'll try to summarize some of the central points about the
writing part below.

The problem many (all?) people face when they have to sit down and write
something is the blank sheet of paper (or computer screen, but let's
keep the paper analogy for now, it applies to electronic writing as
well).  It happens to me all the time.  For me getting started is the
hardest part and after I have somehow produced a rough skeleton of the
content I manage to expand and refine it in a fraction of the time it
took me to get to that first milestone.

So how do I manage to make that initial phase less painful and more
productive?

Remember the old piece of coding wisdom "Avoid premature optimization."?
It applies to writing as well, let me explain how.

Say you have written down that magic first sentence. You don't like it,
so you rewrite it; four times. You arrive at 20 pages of text and start
the review phase. You go back to your perfect first sentence only to
discover that given the 20 pages of text that appeared after it, it's
no longer the perfect fit it used to be. You throw it away and rewrite
it, only twice this time. Your work is finally finished and you start
the last review cycle. You have a new idea for a better introduction and
write a new first sentence from scratch, for the nth time.

So how do I avoid this situation?  Usually writing works in iterations.
First you create a rough draft, then you refine it n times.  Accept that
the first draft is just that - a draft - and that draft quality is more
than sufficient for it.  If you try to produce a high quality draft, you
will WASTE TIME in big quantities.  Doesn't "high quality draft" sound
like a contradiction in itself?  It does, because it is, so don't try to
achieve the impossible. 

Still creating that first draft is not trivial and avoiding the
above-mentioned pitfalls can be difficult.  Here are two techniques that
I find effective:

1) bulletted lists

Bulletted lists are great because they free you completely of grammar
and style and quality concerns.  You can start jotting down ideas in no
particular order until you run out of ideas or until you have listed
everything that you want your written work to contain.  The temptation
to "optimize" bulletted lists is near-zero.

Once you have a list of things you can start reordering the bullet
points, adding a bit here and there, giving the list more structure to
make it resemble a rough outline of the text you want to produce.  Then
you can add more details, start writing chapters, etc.  Just remember
that even now you WILL throw away the first version, so don't waste too
much time on it.

2) automatic writing

This is a technique from creative writing that is used to combat
writer's block and works quite well to produce first drafts and ideas.

Here's how it works: Grab pen and paper and set an alarm clock to a
fixed amount of time (fifteen minutes as a rough guideline).  Then start
writing and during the set amount of time you may never, under no
circumstances, stop writing.  Style, orthography, even grammar, toss it
all aside and write.

If you hit a block and hesitate, you can use an escape rule.  Repeat the
last word/sentence, write something that rhymes, starts with the same
letter, whatever.  Anything that keeps the pen pressed to the paper is
fine.

When the alarm goes off, drop the pen (or continue if you are in a flow)
and review what you have written.  Results are often surprising and even
if not, normally you have a draft that can be refined into something
useful.


OK, I'm cutting down on it here, it's been pretty long-winded already,
but I thought I might share some of my experience with you.  I often
find writing quite hard and these techniques help me a lot.

So, don't worry Wanderer, I'm sure you can pick up writing skills with a
bit of patience.  Guillaume probably did it without worrying too much
about the outcome beforehand, which is pretty much the spirit of the
above-mentioned techniques.

Diego