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:"Collier,Michael" <Michael -dot- Collier -at- CNALIFE -dot- COM> Date:Wed, 11 Mar 1998 11:00:38 -0600
Boy, does this sound familiar. I was in a nearly identical situation in a
previous position. About 35 programmers, Lotus Notes, only tech writer,
programmers were always putting out fires, enterprise system, order
What documentation there is scant, and found in Lotus Notes, Word,
leaf paper, and in old manuals and on individuals' PCs, Notes
hardcopy forms, and in many brains.
Plan of Action: I am trying to get management to buy in and promote
documentation process. Yes, I have been hired but not empowered. No
time because they are putting out fires. Management by crisis and
Been there too!
1. I am putting together information to give to management to
that documentation needs to be promoted by them and made part of the
and a mandatory part of the applications process.
2. Develop a plan that covers what the documentation consists
existing and future applications.
3. Chart a process for developing documentation procedures and
4. Start developing documentation standards and departmental
5. Give target areas (i.e. Operations - updating computer and
operations manuals; document architecture and standards; update
recovery procedures; Applications - document architecture and
critical business applications first, then be made part of the
the beginning on new projects, document existing applications;
Networking/communications - document disaster recovery procedures,
architecture) and time lines.
Can you give any suggestions whether or not these five items make
what is missing. Where do I go to get proof for the pudding - how do
information to back up my reasons for documenting (besides the fact
have lost a lot of good programmers and their knowledge)
Your five items make a lot of sense. As to proof for the
pudding--New programmers will be productive sooner, cutting training costs.
Eventually there will be less fires to put out (or it least they will take
less time to extinguish).
How do you go from convincing personnel that documentation is
important to implementing the procedures? When programmers are busy putting
out fires and the new ones are looking for answers and help, how do I get
in the picture and produce something that is added
You desperately need a development or IS manager to help push the
documentation effort. The fact that you are there and advocating
documentation is a massive change in the company culture and the job ahead
of you is extremely difficult. Programmers are not going to listen to the
lone tech writer but will cooperate when pushed by management. You need to
be in meetings run by this manager attended by programmers, wherein you can
update them on your efforts, ask them for feedback, demonstrate how what you
have implemented or intend to implement has or will solve some of the
department's urgent problems.
Does your company have a knowledge base expert--perhaps whoever
decided that Lotus Notes should be implemented? Companies are starting to
pay more attention to this need so that valuable knowledge developed by the
company is not lost. Information and knowledge are often a company's most
valuable asset. Your work contributes to this enormously and you need to
make the right people realize this. A knowledge base person would be an
excellent ally in your efforts.
In my case, when I got the Notes databases up and running, the
programmers loved it. They could actually find stuff without having to
crowbar it out of somebody's home directory. If you're using the Domino
server HTML and search engine features, get them working as well. Enlist the
aid of a Notes developer if necessary. Your efforts will eventually be
appreciated, believe me.