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.
Subject:Re: Write and They Will Come From:John Posada <john -at- TDANDW -dot- COM> Date:Wed, 11 Mar 1998 12:07:11 -0500
You described my situation to a T.
How long have you been at this place. I started in October and it took
until about Feb to have documentation to START to become part of the
Don't try to change the mentality of the department and you won't get
management to buy into something without being able to demonstrate
actual benefit. You can talk yourself blue in the face. Instead, find an
ally. You only need one and that may take some time. In my case, it was
the person in Operations that was responsible for getting the less
experienced people and bringing them up to speed. I started creating
very short procedures for him so that his operators would be able to
perform specific functions.
Once I strated doing it for him, others saw the benefit and started to
> HELP. If you were a new tech writer and went to work for 35 programmers in
> a department that had *absolutely* no infrastructure existing for
> documentation procedures and were the first tech writer hired there, where
> would you start?
Spend a week or two, or three taking that collection of material and
converting the stuff to some type of uniform collection. Use this
opprtunity to have your style guide evolve.
> Obviously, the old sage that said "Write and they will come" did not work
> with programmers.
> Background: most of what I will be writing will be used by computer
> operators, systems analysts, programmers, and networking personnel. My
> primary customers are personnel within the department. The result of this
> documentation will also evolve into user training/procedure materials for
> customers in other departments. We have a large enterprise system and work
> in a Lotus Notes environment. I have databases which will act as central
> repositories, so the technology end is covered. We have applications that
> cover manufacturing, order processing, financials, and taxes, etc. - all
> the usual business flows.
> What documentation there is is scant, and found in Lotus Notes, Word, loose
> leaf paper, and in old manuals and on individuals' PCs, Notes databases, in
> hardcopy forms, and in many brains.
> Plan of Action: I am trying to get management to buy in and promote this
> documentation process. Yes, I have been hired but not empowered. No one has
> time because they are putting out fires. Management by crisis and adhoc
> culture reigns.
Then they won't have time to look at a plan. Just do it.
> 1. I am putting together information to give to management to show
> that documenation needs to be promoted by them and made part of the product
> and a mandatory part of the applications process.
No. Just get the stuff under people's noses. Keep an ear open. If you
happen to overhear of one of the programmers having a problem that
you've put on paper, just run off a copy and tactfully mention that you
may have something documented that may help. Give the person the copy
and leave it alone. Sooner or later, that person may come back asking if
you happen to have a document on something else, if you do, great...if
you don't, this is your introduction to developing a new document.
Volunteer your writing services. I even volunteered to help one of the
department managers to rewrite ads for hiring. Here's where having some
marketing experience helped. In one case, the manager that I rewrote a
job ad for mentioned that he recieved 3x more resumes by a much higher
caliber of applicant.
>2. Develop a plan that covers what the documentation consists of for existing and future applications.
No, unless the plan is for your use. They don't want to see another
"plan"..they want to see real stuff.
>3. Chart a process for developing documentation procedures and requirements
No. if you are successful, they will see the process. A hint. When you
give someone a document, make sure it has a very destinctive cover.
Then, as management wanders around, they'll start to see these documents
sitting on people's desks. Of course, sooner or later, one of them will
pick it up and thumb through it, notice what it is and start to ask
questions about it.
>4. Start developing documentation standards and departmental style guide.
Only for your benefit. Just get the stuff out there.
> 5. Give target areas (i.e. Operations - updating computer and
> operations manuals; document architecture and standards; update disaster
> recovery procedures; Applications - document architecture and standards and
> critical business applications first, then be made part of the process from
> the begining on new projects, document existing applications;
> Networking/communicaitons - document disaster recovery procedures,
> architecture) and time lines.
Also...develop a NEW method of distribution. It is important that it be
a new way. Then, once you have something in place, because it is new, it
will give you the opprtunity to ANNOUNCE it. I did this through a
company-wide email broadcast announcing the availability of a new branch
off the existing intranet where new material could be downloaded via
and SELL, SELL, SELL
John Posada, Technical Writer (and proud of the title)
The world's premier Internet fax service company: The FaxSav Global
-work http://www.faxsav.com -personal http://www.tdandw.com
-work mailto:posada -at- faxsav -dot- com -personal mailto:john -at- tdandw -dot- com
-work phone: 908-906-2000 X2296 -home phone: 732-291-7811
My opinions are mine, and neither you nor my company can take credit for
HEY! Are you coming to the NJ TechWriter lunch? So far, about 10
of us are. Ask me about it.