Re: Document processes and process documents

[Rahel Bailie <rbailie -at- CASTLETON -dot- COM>]

Rohina wrote:
>I have been asked to prepare a process document  with
standards for writing a Technical Manual. My audience will be the
programmers who wrote the software and other technical people. The
manual will have to be pretty technical and very indepth defining
backend stuff and all that.

When I began my last job (we're being bought out by another company,
where I'll be working), I found myself in the same position. I decided
to use the same process document as the engineers did to develop their
hardware and software specs because (a)it was there, and created a
structure, and (b) the familiarity of the format I hoped would increase
SME buy-in.
For content, I borrowed heavily from the Sandra Pakin book "DDM: The
Documentation Development Methodology." Here's some feedback from my
little corner of the world.


>I have never really carried out a task like this, I would appreciate it
>if I can get some help on:

>* What should go into the Process Document - E.g. How I should go
about writing the Technical Manual - guidelines etc.

It might help to break the process down into the review cycles, i.e.

1. DOCUMENT DEVELOPMENT PROCESS
1.1 Determine the review process
1.2 Review the document plan
1.3 Review the first draft
1.4 Review the rewrite
1.5 Review the final version
2. DOCUMENT SET
2.1 Techncial Manual
2.1.1 Proposed Table of Contents
etc.

My process documents outline the steps within a particular review cycle.
For example, review of the first draft might read:

"Technical reviewers check technical accuracy, completeness, and
suitability of topic emphasis. Wording and style issues are irrelevant
at this point, unless it makes the content unclear. Market reviewers
check for content organization, and that the material will be complete
and useful to users.
1. Author creates first draft with mocked-up graphics.
2. Author circulates draft to reviewers.
3. Reviewers mark up changes to be made.
4. Author and reviewers discuss proposed changes at technical review
meeting."

No matter what you put into the document, MAKE SURE THE SMEs SIGN OFF.
That's critical to keep them from arguing over process later on,
particularly when they gripe about taking time out for a technical
review meeting.

>* What should go into the Technical Manual - How it should be
structured out - What are the topics I should cover?

From a hardware side, it's: get it open, get it in, get it up, get it
on, get it over with, "it" being the product, of course. In the proposed
table of contents, I usually give a general picture, something like
this:

1. Customer support information
2. Foreword
3. Product overview
4. Setting up the unit
5. Installing the unit
6. Configuring the unit
7. Troubleshooting
8. Upgrading software
9. Technical specifications
10. Glossary
11. Index

Of course, that gets refined as I get to know more about the product. (I
ask people to agree to this ToC in principle.) I leave the software
explanation to the many tech writers on the list who do that.

> * Most Important are there any set/defined Standards for writing a
Technical Manual that I can follow??

Tough question. There's no set standard; everyone has a favourite
author/guru, manual, model they follow or, in absence of that, their
corporate style guide. ;-) IMHO, standards such as clarity, usability,
and so on are the basis of our profession as tech writers. How we apply
those standards (i.e. is my interpretation of clarity also the
readers'?) is what separates the respected tech writers from the others.

Rahel Bailie
Vancouver, BC, Canada


 From ??? -at- ??? Sun Jan 00 00:00:00 0000=