Review and revise

Why review?

Once you have finished with your first draft, it can feel like you're done, but you're not. Reviewing your document is a critical part of the writing process that will allow you to be able to catch inaccuracies, clarify ambiguities, clean up poorly written sentences, and make sure that everything your audience requires is covered before your document is shared. To review is to take a high-level look at your document to ensure that it satisfies its goal.

Reviewing is especially important when writing code documentation. If your document is unclear or brushes over important aspects of the code, the documentation will not be helpful when another developer needs to update or maintain the code you wrote.

You may feel too close to your draft to make the major changes necessary. Because of this, it may be helpful to collaborate during the revision process. Depending on the project, there may be editors or content reviewers on hand who can look at your writing with fresh eyes and help you to understand what changes your draft needs.

However, if no one else is available, the two processes listed below will allow you to get out of your head and be able to read your document with fresh eyes.

As you continue to write and review documentation, you might find that you begin to add your own steps to create an individual review process that works for you.

Review process: Question and Answer

As you re-read your document, make sure that it answers all the questions below with a firm yes.

• Is the document addressing the intended audience?

  • Have all the questions that you wrote down for yourself to answer in the document been answered?

• Is the document prioritizing the information that is most important to the audience?

• Will this answer the audience's questions?

• Are any assumptions you have made about the audience stated clearly?

• Is the document structured in a clear and logical way?

• Is the document supporting all claims and facts with evidence from accurate and relevant sources?

• Is all the information in the document relevant and up to date?

• Is there enough information present in the document for someone else to come in later and successfully update it?

Take a look at the README file below with the questions listed above in mind. Does it answer all of them? Are you left wondering or confused about what is being discussed, how to install, or how to collaborate?