- Content is an afterthought. Technical content is seen as a necessary evil and not a strategic asset. Documentation is created at the last minute, content creators are not full members of the product teams, and the “just get something out there” mentality prevails. Authors pick up whatever tools they can—Microsoft Word, an open source wiki, web-based word processors, and so on.
- Content solves the wrong problem.This problem is especially common in software documentation, where authors focus on providing click-by-click instructions (“Click the Name field and type in your name”) instead of useful, hard-to-find information (“Omit apostrophes and any other special characters, which result in an ‘invalid name’ error message”).
Note: In many cases, the critical information needed in technical content reflects product design problems. The Name example would be better addressed by creating software that either supports apostrophes or by having the software remove the characters and notifying the user (“Using OKEEFE instead of O’KEEFE”).
- Content creators have the wrong skillsets. Content creators must be capable of understanding the product and explaining it to others. Many product developers fail the second test. Some writers fail the first test. Effective technical communicators balance these two requirements.
- Correct. You cannot save technically incorrect information with snazzy formatting.
- Relevant. Accurate information is not enough—readers want information that addresses their specific issue.
- Concise. Most readers do not want to wade through huge volumes of information to find what they need.
- Accessible. Readers must be able to get at the information; that means, for example, providing graphics that do not use tiny type and addressing the needs of readers with varying degrees of literacy, visual acuity, computer skills, and so on.
- Usable. Readers must be able to find the information they want and understand it.
This appendix offers a quick overview of factors that contribute to useful content. For detailed information about developing effective technical content, refer to Technical Writing 101: A Real-World Guide to Planning and Writing Technical Content (scriptorium.com/books/technical-writing-101).