Style guides - doc standards vs processes?

["Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>]

I'm coming late to the table on this (just came back from an exhausting and
exhilirating weekend at the 2001 World Fantasy Convention), but if I've got
the attributions right, it was Johanne Cadorette who said: <<A documentation
roadmap would also be useful. Map out the documentation process from a-z,
matching each step in the development process to one in the documentation
process.>>

I'd love to do that, but as is the case in most development operations, the
software development process isn't sufficiently mature to allow for this.
That by no means trivializes Johanne's suggestion; it's a really good one,
and even though we're not nearly there yet, I keep agitating to move us in
that direction.

Lucinda Metzger continued: <<I'm curious -- how many of you include a
"documentation roadmap" as part of your style guides? How many of you have
written up any type of roadmap at all?>>

I've been an advocate of a related approach for quite a while: make the
style guide part of how people work, rather than an online repository of
never-read guidelines. See, for example, the following article:
Hart, G.J. 2000. The style guide is dead: long live the dynamic style guide!
Intercom, March:12-17.

One result of this approach is that we've created a fairly powerful task
management system in MS Outlook that lets us track the various steps in
writing, reviewing, editing, and laying out our publications. Simplistically
speaking, we linked Outlook's "task" functions with Word to let us route
documents effectively between those responsible for each task and to assign
trackable deadlines that the documentation supervisor can monitor to keep
things on track. As part of this system, we've included the steps in the
documentation process, in order, as part of the task system, so that all a
user need do is open the currently assigned task, then open the popup task
menu to select the next task in the sequence. (In case the user isn't sure
what to do next, we've taken two steps to help: the order of tasks that
appears in this popup menu follows the actual process order, so users need
only pick the next task on the list in most cases, and we've added a
flowchart to visually display that order in case they can't remember the
process even after training.)

In addition, we've designed a Word template for our reports that contains
preformatted, pretyped headings to remind authors what goes in each section;
simple affordances, such as "write a 50-word abstract here"; and links to
the planning documents and the most important style guidelines, which are
stored on our network. All new documents are written using the template.
This system arose from a "Kaizen" process in which we carefully analyzed our
publications process, identified obstacles and solutions, and developed a
system that eliminated or minimized the obstacles. In so doing, we cut
documentation times by more than half. (I'm hoping to write this up as a
case study for _Technical Communication_ when time permits. Maybe early next
year...)

--Geoff Hart, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca
Tarzan's rule of data processing: Never let go of one vine until you have a
solid hold of the next.--Anon.
 

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Be a published author!  iUniverse gives you: a high-quality paperback, a
custom cover design, and distribution to 25,00 retailers.  Join our almost
10,000 published authors today. http://www.iuniverse.com/media/techwr

Have you looked at the new content on TECHWR-L lately?
See http://www.raycomm.com/techwhirl/ and check it out.

---
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.