How do people do this?

[Malcolm Tredinnick <malcolm commsecure com au>]

I am wondering how people approach writing their GNOME documents (and
anything else they do involving Docbook style markup). This is more idle
curiosity than anything else.

Currently, I am finding it most convenient to write my documents once in
plain text and then, after correcting that draft, mark it up and then do
another editing pass to correct any stylistic problems that result from
the markup. Of course, the editing passes are usually multiple passes
and even after publishing things I will notice places that need
correction.

I have also tried doing the markup as I go along the first time (which I
tend to do for short documents anyway), since I have a fairly hefty set
of vim macros setup to make adding tags flow fairly naturally into my
typing. This way feels a bit awkward, though (the macros aren't entirely
natural constructs, since otherwise they would be triggered by normal
typing of English), and I find that I often lose the thread of what I am
trying to say whilst adding the tag soup.

However, the current technique is not perfect, either. The main problem
I find is that I tend to write with a mental image of what bits will end
up at what presntational level (sect1, sect2, tip, callout, etc) and
sometimes that information gets lost between the plain text version and
the markup phase.

Also, I find the markup phase to be mind-numbingly boring. Honestly, I
would rather clean my apartment than markup documents sometimes and I
suspect that this stops me writing more than I do (this is _not_ a quiet
plea for help, since I don't think anybody would _enjoy_ doing the
markup).

Looking at my behaviour lately (where I have been doing a lot of writing
both for GNOME and for work), I seem to have developed some kind of
simplistic markup language that is sort of Wiki-inspired or perhaps
sub-consciously taken from the Python markup conventions. This just
gives me a shorthand way of recording what tags I want to put around
various things so that I remember when it's markup time.

What do other people do? Does the final editing process just suck for
everybody, or am I missing some cool technique?

Malcolm