Re: Issues about documentation process/management

Subject: Re: Issues about documentation process/management
From: Keith Hood <klhra -at- yahoo -dot- com>
To: TECHWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>, SB <sylvia -dot- braunstein -at- gmail -dot- com>
Date: Fri, 13 Jun 2008 09:34:03 -0700 (PDT)

Wow. Ouch.

You should write up a business case that details the problems being caused by the current schedule/deadlines, and make an argument for making some alterations to them. That business case must include your ideas on how to improve the situation, not just a list of complaints. Anything you write about proposed changes needs to be couched in terms of how the changes would improve the product/process and benefit the company; if it's just benefits for the sake of the writers, the bosses probably won't care. A good business case *might* do some good in trying to change the situation.

Unfortunately, there are companies that really just don't care about problems in the docs branch, and you have to prepare for that eventuality. Also, the people who are causing you a time problem with their schedules may be under pressure from their highers, and they may have way to improve the time situation.

1. When you run into a situation where you donât have time and workers to finish everything properly, you must (if only to cover yourself) immediately notify the person who is responsible for making a decision and *press that person* for a decision on what to prioritize. If that person has the right personality, doing that often enough will eventually get to him and heâll realize that something has to be done. (If the wrong personality, it will eventually backfire but you still have to CYA.)

1.a. Consider the documents that are delivered with the product, and if at all possible, boil them down to the barest absolute essentials. If you can reduce the documents significantly, that mitigates and may possibly avoid the problems with too much doc per worker. This would be best worked out with the business analysts and other personnel who may have information from the users about what they need and/or want in the functionality; that would be a yardstick for what really has to go into the docs. Look hard at ways to simplify your process. Are there places where lots of verbiage could be replaced with graphics or tables or lists that are quicker and easier to create? Later, if you ever get any time, maybe you could change your documentation model: Deliver nothing but a bare-essentials QRG with the product. At the same time, put together a web site that customers can access for more details. That web site can be updated if and when time is available.

1.b. Start campaigning to hire more people.

2. Thereâs no way for you to determine what is âbestâ for the user because they will all have their own opinions on the subject. That said, you should consider that some customers may have older, lower-capacity systems, or the companies you send docs to may be cheapskates that wonât pay to upgrade RAM. So, there will be some users of your docs who may have problems dealing with huge PDFs. And it should be fairly easy in smaller files to stick in a few lines that relate each file to others in a set. In each separate document, put a table or chart that shows the current doc in graphic relation to others that pertain to that product.

3. If you sacrifice either quality or quantity there will be problems. I believe that if you absolutely must prioritize one or the other, you should give priority to content, to covering all the required topics. If you donât have enough time to do proper editing so some spelling and grammar errors creep in, users may scoff at the documents and lower their opinion on the writersâ abilities, but they are less likely to downgrade their opinion of the company or the products. If the documents omit content that the reader must have in order to use the product properly, thatâs even worse. Readers may think that the product was modified after the documents were written, which makes them think the company isnât competent to coordinate and control its development process. Worst of all, that could cause problems in their business, which would be worst of all. That said, there are some things that absolutely MUST be correct no matter how much time it
takes. Those are things that would affect the correctness of user actions â things like having the right (latest version) screen caps and the steps in numbered procedures. If you give an incorrect definition of an acronym or special term, that does less harm than giving the wrong steps in figuring tax amounts.

3.a. Start looking at possibly instituting a content management system so you can have one-point control of changes to content. If you can chunk the information properly, you can get a lot of the content down to where changes can be managed by one source-control specialist, leaving the other TWs free to develop content and worry about editing, formatting, templates, etc.

4. Who is your boss, a document manager or a training department manager or director of sales or what? If his job really is directly related to developing and fielding the product, he should be directly concerned with the documentation. Why is he disconnecting? Does he have orders from above to concentrate on other things?

4.a. Is his current disconnection with the documents an opportunity? Think about what might happen to your stock in the company if you stepped into the breach and started proving to the other TWs the leadership that he is currently abrogating.

5. Refer to what I wrote in paragraph 3. Do the business case thing and express your opinion. Even if it doesnât actually do any good, at least it covers you.


Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include support for Windows Vista & 2007
Microsoft Office, team authoring, plus more.

True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity!

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

Issues about documentation process/management: From: SB

Previous by Author: RE: Display, Displays, or Appears
Next by Author: Re: Article in front of hardware or software
Previous by Thread: Re: Issues about documentation process/management
Next by Thread: RE: Issues about documentation process/management

What this post helpful? Share it with friends and colleagues:

Sponsored Ads