# Self-editing

<br />

> [!NOTE]
> **Estimated Time:** 10 minutes

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.

> [!NOTE]
> **Note:** The tips in this unit build on the basic writing and editing skills from Technical Writing One. This unit includes a summary of useful editing techniques from that course. For a more detailed refresher, visit the [self-study units](https://developers.google.com/tech-writing/one) from Technical Writing One.

## 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](https://developers.google.com/) site follow the
[Google Developer Documentation Style Guide](https://developers.google.com/style). 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](https://developers.google.com/style/highlights).

> [!NOTE]
> **Note:** For smaller projects, such as team documentation or a small open source project, you might find the highlights are all you need.

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](https://developers.google.com/tech-writing/one/active-voice) to make clear who's performing the action.
- Format sequential steps as [numbered lists](https://developers.google.com/tech-writing/one/lists-and-tables).
- 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](https://developers.google.com/style/person). Refer to your audience as "you", not "we".
- [Place conditions before instructions](https://developers.google.com/style/sentence-structure), not after.
- Format [code-related text as code font](https://developers.google.com/style/code-in-text).

## 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](https://developers.google.com/tech-writing/one/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](https://en.wikipedia.org/wiki/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](https://developers.google.com/style/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.

#### Click the icon to see the answer.

To help your audience understand your document, apply these basic editing
principles:

- Use active voice instead of passive voice.
- Consider using simpler words that mean the same thing.
- Include links to background information.
- Break long sentences into shorter sentences or lists.

*** ** * ** ***

<br />

**Next unit:** [Organizing large documents](https://developers.google.com/tech-writing/two/large-docs)