Imagine that you just wrote the first draft of a document. How do you make it better? In most cases, working towards a final published document is an iterative process. Transforming a blank page into a first draft is often the hardest step. After you write a first draft, make sure you set aside plenty of time to refine your document.
The editing tips in this unit can help turn your first draft into a document that more clearly communicates the information your audience needs. Use one tip or use them all; the important thing is to find a strategy that works for you, and then make that strategy part of your writing routine.
Adopt a style guide
Companies, organizations, and large open source projects frequently either adopt an existing style guide for their documentation or write their own. Many of the documentation projects on the Google Developers site follow the Google Developer Documentation Style Guide. If you've never relied on a style guide before, at first glance the Google Developer Documentation Style Guide might seem a little intimidating, offering detailed guidance on topics such as grammar, punctuation, formatting, and documenting computer interfaces. You might prefer to start by adopting the style-guide highlights.
Some of the guidelines listed in the highlights are covered in Technical Writing One. You might recall some of the following techniques:
- Use active voice to make clear who's performing the action.
- Format sequential steps as numbered lists.
- Format most other lists as bulleted lists.
The highlights introduce many other techniques that can be useful when writing technical documentation, such as:
- Write in the second person. Refer to your audience as "you", not "we".
- Place conditions before instructions, not after.
- Format code-related text as code font.
Think like your audience
Who is your audience? Step back and try to read your draft from their point of view. Make sure the purpose of your document is clear, and provide definitions for any terms or concepts that might be unfamiliar to your readers.
It can be helpful to outline a persona for your audience. A persona can consist of any of the following attributes:
- A role, such as Systems Engineer or QA Tester.
- An end goal, such as Restore the database.
- A set of assumptions about the persona and their knowledge and experience.
For example, you might assume that your persona is:
- Familiar with Python.
- Running a Linux operating system.
- Comfortable following instructions for the command line.
You can then review your draft with your persona in mind. It can be especially useful to tell your audience about any assumptions you've made. You can also provide links to resources where they can learn more if they need to brush up on a specific topic.
Note that relying too heavily on a persona (or two) can result in a document that is too narrowly focused to be useful to the majority of your readers.
For a refresher and more information on this topic from Technical Writing One, see the Audience self-study unit.
Read it out loud
Depending on the context, the style of your writing can alienate, engage, or even bore your audience. The desired style of a given document depends to an extent on the audience. For example, the contributor guide for a new open source project aimed at recruiting volunteers might adopt a more informal and conversational style, while the developer guide for a commercial enterprise application might adopt a more formal style.
To check if your writing is conversational, read it out loud. Listen for awkward phrasing, too-long sentences, or anything else that doesn't feel natural. Alternatively, consider using a screen reader to voice the content for you.
For more information on adjusting the style of your writing to suit your audience, see Style and authorial tone.
Come back to it later
After you write your first draft (or second or third), set it aside. Come back to it after an hour (or two or three) and try to read it with fresh eyes. You'll almost always notice something that you could improve.
Change the context
Some writers like to print their documentation and review a paper copy, red pencil in hand. A change of context when reviewing your own work can help you find things to improve. For a modern take on this classic tip, copy your draft into a different document and change the font, size, and color.
Find a peer editor
Just as engineers need peers to review their code, writers need editors to give them feedback on docs. Ask someone to review your document and give you specific, constructive comments. Your peer editor doesn't need to be a subject matter expert on the technical topic of your document, but they do need to be familiar with the style guide you follow.
Exercise
If you have a document that you're working on, use one or more of the tips on this page to make it better. If you don't have a document in progress, edit the paragraph below.
Determine whether or not you can simplify your document through the use of terminology that is equivalent but relatively shorter in length and therefore more easily comprehensible by your audience. It's important to make sure your document is edited before it is seen by your audience, which might include people that are less or more familiar with the matter covered by your document. The first thing you need is a rough draft. Some things that can help make your document easier to read are making sure you have links to background information, and also checking for active voice instead of passive voice. If you have long sentences you can consider shortening them or implementing the use of a list to make the information easier to scan.
Next unit: Organizing large documents