Chapter 13: Technical Editing¶
This chapter describes the work of technical editors.
Technical editing instills consistency throughout a body of documentation, improves the overall quality of the docs, makes your content more accessible, ensures that content follows good information design principles, an trains writers to write well. (pg118)
It also briefly mentions style guides, discusses how to edit well, and how to improve writing style.
Note that technical editors are not “just” proofreaders. They may catch typos, but they are also there to create and maintain style guides, check documentation for style and tone, advise on content organisation, and so on.
Discussion Summary¶
As a dedicated role, technical editors seem rare: “as mythical as unicorns”, to quote one participant. However, this doesn’t mean technial editors aren’t valued: they “seem like something everyone would want”, can help ensure consistency across content, and remove personal bias in writing. As well as simply not having a dedicated editor, people in the discussion and the chapter itself mention time pressures. In a fast-paced agile environment, who has time for lengthy reviews? Treating editing like code QA can demonstrate its value, and ensure time is set aside for it.
Some people can draw on SME reviewers who also act as proofreaders and editors, or arrange peer reviews within the writing team. Lone writers can find it especially difficult to maintain consistency over time, with no team for peer reviews. To mitigate this, some hire proofreaders and/or editors. When you don’t have an editor, a style guide can still help maintain consistency.
The discussion around editing lead to questions around over- and under-editing, and how much of the writer’s voice should be in the documentation. Some felt that removing the writer’s individual voice was a step too far, while others argued that (ideally) you should not be able to tell by voice or tone who has written a particular document. This differs across content types: blog posts might be more informal and personal, user manuals less so. Generally, documentations should maintain a consistent tone throughout, even if multiple writers are working on it.
