TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
SIANNON -at- VISUS -dot- JNJ -dot- com [mailto:SIANNON -at- VISUS -dot- JNJ -dot- com] asked:
"For those of you who have been called upon to bring order out of chaos,...
How have you approached establishing a
documentation structure? What tips and tricks have you amassed over the
years that you'd be willing to share? Have you developed an "archetype"
structure to bring with you if/when you move to another job?
"I think this "organizational" phase is the most often undervalued yet vital
segment of the job; I've run across a couple situations where lone
techwriters I've met have been given *no* guidance or direction about the
doc set needed for the projects they work with, and invariably they find
themselves having difficulty with scope, depth and prioritization of their
docs."
______________________________
SIANNON:
I think the first thing you have to do is go around, introduce yourself to
the various managers and SME's and ask lots of questions about what kind of
information they have, such as specs, design notes, meeting minutes, memos,
e-mails about how the product works or doesn't work, and where they store
such information. Tell them that you want to gather as much information as
you can without taking a lot of their development time.
Ask for "read-only" access to any files that may be on a server or in a
shared development database. Even if nothing has been formally documented,
there is lots of informal information around. Also talk to the marketing
folks, to find out what they are selling, and what documentation they think
the customers will expect. Invest in cookies or snacks to feed the
developers, or put a bowl of candy on your desk to lure them by, and then
ask them to e-mail you any information they may have that should be covered
in the documentation. Then read it all several times, make yourself an
outline of the product's functionality, features, components, etc., and a
list of what documents may be needed.
Gather all the information that you can about what kind of customer or
industry or product niche that the product will be marketed for. Find out
what kind of support is planned for the product after it is launched. Will
there be a help desk, or customer support reps, or will an outside service
agency handle support, or whatever. Make more notes and or outlines.
When you think you have a coherent idea of what is what, get your boss or a
manager to call a meeting of the managers, the head developer, the team
leaders, marketing, and whomever else has a stake in the product. Then,
before the meeting, send everyone on the list a copy of a summary of what
you know about the product, the market, the customer, the planned support,
and what documentation, help, etc., that you recommend, with a description
of each and who it is for. List approximate sizes, a draft TOC (if you can)
and time requirements for each. This is to give them something to evaluate
and shoot at. Your assumptions do not need to be right, because you are
only giving them a target to consider.
At the meeting, let them discuss your summary and recommendations, challenge
your assumptions, etc. Take notes as fast as you can, or get permission to
record the meeting. Some of the managers at this meeting may have never
considered documentation requirements before, or have radically different
assumptions of the target customers, etc. You'll probably have to revamp a
lot of your information and recommendations, or come up with additional
budget information, but once these powers-that-be reach some kind of
concensus, you and they will have a much better idea of what they want or
need, and you can get to work to start producing it.
Then ask to be put on the various departmental distribution lists, so you'll
get copies of meeting minutes, change notes, problem resolution memos, etc.
You'll receive a lot of stuff unrelated to what you need, but you'll get
early warnings of changes or problems that may affect release or require doc
changes. You'll already know who is handling what, so that you can follow
up and get it in the docs.
This is what I have done as the only writer in several situations where the
company knew that it needed documentation, but they have never had anyone to
do it before. You're sort of jumping into a fog with both feet, but if you
have confidence, you'll get through it in one piece. Good Luck
Margaret Cekis
Margaret -at- mediaocean -dot- com
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Attention ForeHelp and Doc-to-Help Users! Upgrade your existing product to
RoboHelp for FREE, through January 15th. RoboHelp can import your existing
Help projects! Learn how else RoboHelp can benefit you. www.ehelp.com/techwr
---
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.
