Concise Writing

Concise Writing

Rely on your development team members to assist you in producing concise technical content. All distributed content, including online and hard copy content should be reviewed for accuracy, clarity, and usability. Development, training, technical support, marketing, and sales personnel should be included in your reviewer list.

Feedback from users is also valuable during the content development cycle. Although in-house user feedback is important, customers willing to review content are more likely to provide uncensored and unrestrained comments regarding ease of use, navigation, and overall presentation. Navigation is often reviewed last since the table of contents and index are generated near the end of the development cycle.

If usability testing is included in the product development plan, ensure that documentation testing is also included. Usability testing generally occurs immediately following the beta development cycle. If the development schedule is too short to perform formal usability testing, ask your reviewers to use your procedures as well as any installation and configuration steps that may be available. Training and technical support reviewers may also be able to provide you with user comments from previously released products.

Interviewing users particpating in usability testing provides accurate feedback, If you are participating in a comprehensive usability test, make sure you are able to interview all test participants about content and navigation issues. Additionally, if your company has previously introduced products, interview support and training personnel. Usability testing, performed in a carefully monitored lab environment outside the product development cycle, should also be performed on a regular basis to monitor document success.

Here are some concise technical writing tips:

Avoid compound and complex sentences*
Include an index and table of contents
Include answers to the most frequently asked questions
Include examples, illustrations, and flow diagrams
Plan documentation to address i18n and L10n issues

*Note: English may not be the primary language of your audience.

Keep in mind that users need specific answers quickly and are unlikely to read a document cover to cover. Thus, design your content to assist your audience and minimize support calls. Remember, a robust index and table of contents are essential to a successful content search. Keep in mind that when users can't find answers in the documentation, they call your support organization.

Managing a documentation project may cause you to underestimate your writing development time. To minimize your management downtime, consider these guidelines:
  1. Specify the area/s you wish each reviewer to scrutinize in your cover letter
  2. Strictly adhere to your documentation plan and schedule
  3. Use revision controls to manage all files, including graphics and tables
  4. Strictly adhere to the company style guide