Technical Comms Process Nf

Editor's Notes

• #2: Project management is a subject of growing significance in today’s business world. As projects become increasingly complex, as managing time and resources becomes more unwieldy, and as competition increases, organizations are searching for more effective ways to manage the projects they undertake. A project is a task which must be completed within budget and by a specific time; which is usually, but not always, carried out at once. Examples include preparing a presentation for a major meeting, installing a computer system (including training documentation), or introducing a new product (including sales proposals and marketing data sheets).
• #3: A documentation project leader (or manager) plans and coordinates the activities of a documentation project. A project leader can be the sole writer on a project or the lead writer on a larger, multi-writer project; ensuring that the project passes quality checks, and is completed on time and within the budget set for it. To be successful as a project leader, you must work well with your peers and motivate the members of the writing team, have excellent oral and written communications skills, manage time, people, resources, and multiple responsibilities effectively, interview and evaluate new writing candidates, and make recommendations to management.
• #4: The following are some administrative tasks performed by the project leader: 1) anticipates problems affecting the project group, 2) schedules the writing and production resources for the project, 3) delegates the project writing tasks, 4) forecasts the special needs of the project and ensures that those needs are met, 5) informs management and peers of the project status regularly,
• #5: 6) creates documentation plans and monthly status reports for all new projects, 7) provides management with performance evaluation information for each member of the documentation project team, 8) ensures that all documentation project tasks are completed, and 9) keeps records of project activities.
• #6: The following are some writing-related tasks performed by the project leader: 1) Provides support, mentorship, and training for the writing team members, 2) provides technical direction for the writing team, 3) ensures that documentation standards are met, 4) reviews documentation for readability, accuracy, consistency, and style, 5) identifies future documentation requirements, and 6) suggests and implements process improvements.
• #7: The following are some client-relation tasks performed by the project leader: 1) Explores opportunities with potential customers, 2) analyzes customer documentation needs, 3) negotiates project costs and schedules, 4) coordinates people, budgets, and schedules, 5) acts as the primary contact for all documentation issues, and 6) communicates all relevant project information to the members of the project writing team.
• #8: The following are some suggestions for project leaders: 1) Set expectations and take the initiative to manage them, 2) give a clear explanation of your expectations; remember, what you do not say is just as important as what you do say, so don’t leave anything out, 3) make it clear that developers are expected to spend time with writers, and that documentation is an essential part of the product, 4) keep your channels of communication open to everyone, 5) if necessary, ask for a history of the product, which may make you more aware of product features…
• #9: 6) remain professional at all times, 7) produce detailed plans; it creates a professional atmosphere, 8) have a positive and professional attitude; it lends to credibility, 9) when making group presentations, the environment can be a help or a hindrance to you. Be certain that your presentation is well received by taking the following precautions: If possible, examine the presentation room beforehand, ensure that the audio/visual equipment you need is available and operational, and use visual aids when you can…
• #10: 10) establish a respectful relationship: ask the client and members of the client’s team how they would like to work (e.g., communicating by email, meeting in-person, meeting regularly, etc.), 11) explain your role at the very start of the project, 12) attend client team meetings; this shows that you as the writer are in control, and gains the respect of the team, 13) get to know the client: try to meet with each developer individually at the start of the project.
• #11: 14) look around your client’s office to see any indications of common points of interest, or make a point to have lunch or coffee with your client 15) establishing a rapport may make the client or developer more apt to talk to you throughout the project, making it easier to extract relevant information for your document, and 16) when attempting to obtain review comments, try to have a review meeting for at least the first draft. Go through the manual page-by-page, if necessary. Everything should be settled during this meeting, so you won’t have to chase down reviewers with opposing viewpoints later on. If there are significant changes in subsequent drafts, similar review meetings should be conducted.
• #12: The following presents common problems and solutions during most documentation projects. Problem: Getting inaccurate end-user information from the developer. Solution: Involve the end user at the beginning of the project.
• #13: Problem: Gaining permission to obtain input from a potential user. Sometimes the project team coordinator (project leader or supervisor) does not seem to trust the writer in dealing with the end user. Solution: Build up trust from the beginning of the project. Meet with the project coordinator and explain how you are going to interview the end user. Anticipate any questions or objections and have your responses prepared.
• #14: Problem: Getting the most out of the interview with the end user. Solution: Watch the end user in action. Some people are too busy or are not very effective at answering questions. If you simply watch and ask pertinent questions during the process, you can gain the information that you need more effectively.
• #15: Problem: Not getting review comments from a key reviewer and you feel uncomfortable ‘haunting’ the reviewer. Solution: Speak with their supervisor; speak with your supervisor. Ensure that you document the times you asked for comments and the turnaround time for comments. When sending out drafts, state explicitly in your cover letter that if a reviewer does not give you comments by a certain date, you will assume he or she has approved the draft as is. Set up review meetings for documents. Some reviewers may have trouble documenting their comments, but in a meeting they can express their comments verbally.
• #16: Problem: The client attempts to dictate the style and content of the manuals, set writing deadlines, create templates for the documentation, and doesn’t believe in documentation plans. The client has documentation meetings and does not include the writer. Solution: Hold several meetings with the client and the writing supervisor. With discretion, explain that the writers are consultants who manage the writing effort, instead of passively taking advice and direction from the client. Adhere to high-quality writing and frequent editing cycles. Explain that you may not be able to continue the project without a documentation plan, and maintain reasonable schedules. In most cases, a documentation plan should be drawn up when producing a new document (or set of documents), or when developing a radically new version of an existing product.
• #17: Problem: Availability of developers. Solution: Prepare a list of questions and meet the developer to go over them. However, many developers may want to meet with you immediately; be prepared for that too. Catch the developer walking by and say: “I know you’re very busy, but I need a few minutes of your time to…do XYZ.” Prepare weekly status reports. Distribute these reports to everyone who depends on the documentation, including peers, clients, and managers. As a result, some peers, clients, and/or managers may put the necessary pressure on the developers to help obtain what you need. Ask the developer to delegate another (reliable) information source. Or elevate the issue by asking the developer’s supervisor to free up some time for the developer to give you what you need (for instance, reviewing documentation and answering questions).
• #18: Although some managers and engineers expect you to write the documentation from thin air, it’s your job to educate them about the possible sources of information, such as interviews, legacy documentation, functional specifications, and other sources.
• #19: The following is a list of expectations and considerations which you can introduce to your client at the beginning of the writing project. Each project participant should take the time to define each category to the best of his or her knowledge: Goals, problems, expectations, pressures (e.g., time, other projects or requirements), options (e.g., documentation style, tools, design, the review process, and others), restrictions (e.g., time, decisions, or budget), and likes and dislikes.
• #20: Other expectations include style of work (e.g., casual, formal, email, face-to-face, formal/informal meetings, meetings with the entire team, one-on-one meetings, etc.), special needs (e.g., Section 508 for the reading or hearing impaired), levels of documentation confidentiality, audience profile and task analysis (Who are they? And how and in what context will they use the documentation?), and language translation requirements (if any—What languages? And who will do the translations?).
• #21: Information sources provide the initial ‘ball of wax’ of information. The project consists of your throwing this ball of wax back and forth with your review team, using meetings and draft reviews, and continually growing and refining this ball, until the final product is ‘rolled’ out. It’s your job to find every which way to keep the ball rolling. You’ll probably start out with a rough outline, then a topic sentence for each heading, then paragraphs, then tables, then illustrations.
• #22: The following list describes potential sources of information: developers and supervisors, functional and design specifications, marketing specifications and the business plan, legacy documentation, the development plan, project documents (e.g., a Program Initiation document, a Project Office document, a Business Vision document, Use Cases, an Analysis and Design document, a Test document, a Phase Review document, and others).
• #23: Many reviewers are unsure of what is expected of them. Some shrug off the task by giving the documents a cursory reading at best, feeling that it is solely the writer’s job to publish the documentation. Other reviewers think they are expected to be editors and correct grammar and rewrite content.
• #24: To ensure technical accuracy, ask yourself: Does the documentation accurately describe the way things work? the screens? the procedures? methods? hardware descriptions? To ensure completeness, ask yourself: Are there any omissions? Is everything covered that needs to be covered? Also, is the document readable? Do explanations follow a logical progression? Are they clear and understandable? Do the explanations make sense?
• #25: Good writing should have a flow to it, so that your reader doesn’t feel bogged down or confused. Is too much material covered? Are there unnecessary explanations? Figures? Sections? Or Chapters? Are the figures and tables helpful, clear, and accurate? Are there places where additional figures are needed? Are all references to text, figures, and tables accurate and appropriate?
• #26: For a printed (or hard copy) draft, a cover letter should accompany each draft review copy, explaining the need for a thorough review, and providing a deadline for returning the draft with comments. The document should have ‘Draft Review Copy’ written on each page (e.g., on the header, footer, or as a watermark in large, shaded print). For online documentation, either print out all pages for a hard-copy review and mark-ups; or better yet, develop an online tabular review sheet on the intranet for centralized feedback. After all review comments have been resolved and incorporated, meet with all reviewers to display the online documentation on an overhead projector for further comments. This is the time to put your online documentation in motion, while presenting your information architecture, including the review of all hyperlinks.
• #27: During the course of a typical project there will be a number of reviews. Each review has unique features for writers and reviewers. If the product is new, or there are radical changes, and the development schedule allows for a rough draft, you should have four draft reviews: rough, first, second (final) and signoff. However, if the product has been moderately revised, or there is not enough time allocated to the project, then use three drafts: first, second, and signoff.
• #28: Usually a rough draft can be written, at least in part, from functional specifications. Additional information can be obtained from speaking with developers. Artwork, screens, menus, messages, etc. may not yet be available. Indicate what sections of the document are incomplete because the information is not available. As a reviewer (including you as the writer), answer the following questions: Does the layout seem appropriate? Is the outline complete? Has anything been left out? Are the descriptions and procedures accurate? Specific and complete review comments are most helpful. A set of ‘???’ marks, or statements such as “Huh?” or “Wrong,” are not useful.
• #29: The first draft should be ‘fleshed out’: all headings and sections should include some text to work with. Almost all artwork, screens, menus, and messages should be available. Issues regarding layout, outline, omissions, and the accuracy of descriptions and procedures should have been addressed.
• #30: The second (final) draft document should almost be ready for production. Check carefully for accuracy and completeness. If there are any last-minute functional changes, work closely with the developer so that these can be included in the documentation. If these changes produce numerous changes in the document, do not proceed to the signoff draft review. Instead, incorporate the changes and introduce another second or final draft review; at least one covering the revised sections. Make everyone aware that this may impact the schedule.
• #31: The signoff draft is the reviewer’s last chance to see the documentation before it goes to print or, if it’s online, uploaded to the server. Here are some things to do for the signoff draft: Check that earlier changes have been made. If there have been last-minute changes, ensure that they are correct. Read the document carefully; and make a final check for accuracy and completeness.
• #32: After the draft review process has been completed successfully, the document is officially released and placed on the company network. Notify all relevant users and designated document distributors (e.g., Marketing managers, Product managers, Customer Service managers, IT managers, and others). Depending on their user and business roles, employees can access this document from the network for reading and/or for internal and external distribution.
• #33: For print documentation, indicate the document title, draft or official release version, and release date in the header and/or footer of each page. Use a document version numbering system for draft review copies, where the number to the right of the decimal point is anything but a zero ‘0’, e.g., v0.1, v1.3, v2.7, etc. Officially released document versions should be indicated by a zero ‘0’ to the right of the decimal point, e.g., v1.0, v2.0, v3.0, etc. Archive and shredding policies need to be established to comply with international standards.
• #34: The generalized steps above show a typical development process for a document: 1) Documentation Plan, 2) Draft Review, 3) Official Release and Implementation, 4) Operation Change Order Form (if applicable), and 5) Documentation Control and Maintenance. Note that in some cases, if document updates associated with a new release comprise extensive changes, a revised documentation plan should be drawn up before the draft review stage.
• #35: The following focuses on the elements of an effective meeting and the responsibilities of the person running it: Be clear about the purpose of the meeting. Prepare and distribute an agenda prior to the meeting date. Guarantee participant attendance. Run your meeting effectively. Deal with problem participants. And follow up after the meeting.
• #36: Invited participants are more likely to attend if the purpose of the meeting is made clear. Will the meeting be an informative exchange or a presentation? Perhaps the purpose of the meeting is to collaborate, coordinate, and communicate. The following is a list of some common reasons to have a meeting: To resolve conflicts, to analyze current trends and plan for the future, to improve existing work, and to provide training and development.
• #37: A good meeting agenda has the following essential elements: A clear identity of the group that’s meeting, a limited amount of agenda items with a prioritized list presented in logical order, and a list of people who will contribute to the meeting and what they will contribute.
• #38: It’s very important to ensure that the required people will attend the meeting. Here are some tips to guarantee attendance: Emphasize the necessity of the meeting. Insist on the importance of individual attendance and contribution. Choose a date, time, and location that is suitable to those invited. Follow the agenda. And set up a plan for unexcused absences.
• #39: To run an effective meeting, adhere to the following guidelines: Begin on time. Review the agenda and set objectives. Follow the agenda. Assign action items and establish target dates for their completion. Summarize the agreements reached. Resolve any loose ends and issues before the meeting ends. Record meeting minutes. And end the meeting on time.
• #40: Here are some recommendations for dealing with problem participants at your meeting: Listen, but do not debate. Talk privately with problem members of the group. Try to turn negative behavior into positive contributions. And encourage group censure.
• #41: It’s important to have a meeting follow-up by doing such things as distributing minutes of the meeting promptly, encouraging the completion of action items, and placing unfinished business on the agenda for the next meeting.
• #42: When meeting with the end user, ensure that the end user doesn’t get the impression you’re quizzing him or her. The following questions can be helpful in your interview: What’s wrong with the product? What do you need to know to use it? What knowledge would simplify the process? What other product resources can you provide (e.g., people or information)?
• #43: Assertive behavior is an alternative to personal powerlessness and manipulation. It’s a way to develop self-confidence and respect for others. It will help you do a much better job, and feel better about yourself at the same time. Here are some common barriers to self expression: 1) You don’t feel you have the right to be assertive. For example, you should not question the developer’s opinions. 2) You are anxious or fearful about being assertive. For example, the engineer will complain to your supervisor if you do not do exactly as he tells you. And 3) You lack the skills to be assertive. For example, you know you shouldn’t let the developer run over you like that, but you don’t know what to do about it.
• #44: It’s certain that the project will change as it proceeds. You may be asked to do things that are beyond the original scope of the project. For example, you may be asked to include additional material, or to finish the manual before the agreed-upon completion date. These changes have to be negotiated. Usually there are good business and technical reasons for these requests, and in many cases you can, and should, accommodate for the request with few problems.
• #45: Sometimes, however, it may be very difficult or even impossible for you to comply with a particular request. When this happens, successful assertive behavior can lead to a win-win compromise. Negotiation comprises a particular type of assertive behavior that’s used when you want a win-win outcome; you want both sides to come out ahead. This can be vital when dealing with business associates.
• #46: Writers are frequently exposed to demands and criticism from developers, editors, and others. For example, the developer expects you to take minutes at meetings because you’re a writer, or insists on adding new modules at the last minute without schedule slips, or tells you the final draft is unsatisfactory. People tend to get emotional when criticized, whether it’s justified or not. This can lead to aggressive behavior and over-reaction. When you act aggressively, you react to your perception of the feelings behind the words, rather than to the words themselves. It’s not the anger that you feel that’s inappropriate, it’s how you manage that anger.
• #47: Here are some guidelines for reacting to criticism that will keep the discussion productive: Separate the person from the problem : For example, you are working with another person to solve a particular problem. You may have difficulties dealing with this person, but the person himself is not the problem. Don’t over-generalize : Find out in specific detail what they don’t like, or what they want changed. The developer may say that the manual is poor when what he really means is that he wants a paragraph changed on page 33. Don’t counterattack : This means your anger is out of control, and so is the discussion. Don’t offer excuses or remain silent : This implies agreement; speak up if you disagree.
• #48: Don’t say you agree when you really don’t : Express your opinions and discuss your differences. Don’t be afraid to disagree. Listen : Don’t needlessly interrupt or offer a solution immediately. Let the person talk it out. Try to figure out the real meaning behind the words. Ask for more information : Ask questions that clarify the problem and be more specific, such as: “What don’t you like about this chapter?” or “Why do you want to add this module?” And ask for a solution : Ask questions like, “What do you think we should do about this?”
• #49: Often criticism is deserved. If the criticism is valid, acknowledge it and act on it. Being assertive does not mean ignoring criticism. Here are some assertive ways to react to valid criticism: Accept it : “You’re right. I’ll change it.” Delay : “I’ll need to discuss this with my manager first. I’ll get back to you.” and ensure that you do get back to them. Disagree in part : “I agree with your fist two comments; however, the last one seems unjustified.” Remember, assertive behavior is not a cure-all. But it does support techniques that can help you be more effective, productive, and happier on the job.