Would you like a fries with that style guide?

Subject: Would you like a fries with that style guide?
From: Andrew Plato <intrepid_es -at- yahoo -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 3 Apr 2001 11:33:56 -0700 (PDT)

Mmmm, I haven't had a process tirade in a long time.

>Without a plan and guidelines, a skilled tech writer
> could produce a documentation piece, but it is going to take longer and
> chances are it will not be as consistent.

This may be true, but there is no reason to spend months developing these
plans. My team can plan out an entire 40+ doc set in two days. (But we smell) I
can't tell you how many tech pubs departments I have seen that have binders
full of procedures and plans that are rarely if ever used. Why write them in
the first place? Nobody reads or uses them?

It isn't because the procedures aren't good - they just aren't reality. Most
of them were developed by head-in-the-clouds task forces who envisioned some
perfect universal order to all documentation. It probably felt really good to
spend all the time...but most of it was totally wasted. One person could have
slapped together a plan in two days that was continuously tweaked as the
project progressed and saved a lot of time and resources.

> We are striving for the same thing with the doc plan we are developing. The
> point is to make the process of gathering info and writing easier and help
> us achieve more consistent results. And I have told my writers over and over
> again, if the plan fails to streamline the process of writing, then
> something is wrong. When style guides, standards manuals, doc plans, etc.,
> become nothing but red tape and hoops to jump through, then we have lost
> sight of their real purpose.

I love it when I hear "the process of writing" it makes me laugh. As if there
is a "revolutionary new way to write." Basically, good writers have used the
same process of writing for about 2200 years. Its like this:

- Learn
- Type, type, type (scribble scribble, scribble for pre-1970s writers)
- Edit
- Review and refine
- Get drunk and talk about the tortured genius locked inside you

Now, you can add stuff in there to make it feel like you are more pro-actively
leveraging your synergies - but the process remains the same. If you cannot
master these four basic steps, go back to washing cars or painting cows. Adding
cool sounding procedures to the process won't improve it. They might make it
feel more proper, authorative, and impress the seething hordes at the STC
conference. But it won't help you get text on the page and explain stuff to
your readers.

Unfortunately, a lot of writers have no interest in what they are writing and
hence use complex procedures to mask this fact. This affords them something to
blame when the document is incomplete or incorrect.

"Well, it must be our procedures that failed and produced an incomprehensible
document."

Riiiiiight.

It isn't the procedure, its the flaming moron behind the keyboard who doesn't
know squat-one about the product he/she id documenting. Blame the procedures
(or lack thereof) all you want. At the end of the day, you're readers could
care less that you did or did not use an internationally recognized methodology
or planning system to get the document done.

Wheeee

Andrew Plato


__________________________________________________
Do You Yahoo!?
Get email at your own domain with Yahoo! Mail.
http://personal.mail.yahoo.com/?.refer=text

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available 4/30/01 at http://www.devahelp.com or info -at- devahelp -dot- com

Sponsored by DigiPub Solutions Corp, producers of PDF 2001 Conference East,
June 4-6, Baltimore, MD. Now covering Acrobat 5. Early registration deadline
April 27. http://www.pdfconference.com.

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit
http://www.raycomm.com/techwhirl/ for more resources and info.


Previous by Author: Re: Standards Creep (was "Documentation plans, standards manuals, and more")
Next by Author: RE: Would you like a fries with that style guide?
Previous by Thread: RE: links without underlining them?
Next by Thread: RE: Would you like a fries with that style guide?


What this post helpful? Share it with friends and colleagues:


Sponsored Ads