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 can 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 (option 1)

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?

Review process (option 2)

An alternative way to review your document is to split the review up into five parts:

  • Correct
    • Read your document and (if applicable) try out the steps listed. Every time you think of some necessary information that is not listed, fill it in.
    • Make sure your document is structured correctly, with that information most important and relevant to the reader appearing first. If you are using a pre-made structure, make sure your document adheres to the structure's requirements.
    • It is important that nothing written is ambiguous to the audience. Double-check that necessary terms are defined and nothing could be seen as ambiguous.
  • Complete
    • Have all the questions you asked in your outline been answered?
    • Has all necessary pre-requisite information been added?
  • Concise
    • Read through your document and remove all unnecessary words or phrases. A good rule is that if the document doesn't require it to make sense, you don't need it!
    • Read through your document and notice any repeated words or phrases. Then, remove them by rephrasing or finding a better-suited word for each situation.
  • Clear
    • Is the document's structure logical or does it follow the required structure?
    • Are the sentences short and easy to understand with a clear point?
  • Consistent
    • Is the informal voice used consistently throughout the document?
    • Is the active voice used consistently throughout the document?
    • Does the document follow a clear and consistent structure?

High-level review vs. editing

It's important to distinguish reviewing from editing. These are related processes, but not the same!

Examples of revision

  • Adding new sections and evidence
  • Reorganize the document's headings and sections to place important information at the top.
  • Removing any "I/Me" language or passive voice
  • Altering a thesis statement, argument, or major claim
  • Adding relevant graphics to aid in reader comprehension
  • Removing paragraphs or sections that are unnecessary
  • Checking existing evidence to ensure it's up to date and accurate

Examples of editing

  • Fixing misspelled words
  • Correcting grammatical errors
  • Rewriting unclear or run-on sentences
  • Adding periods, commas, quotation marks, etc.
  • Adjusting word choice for clarity or to avoid repetition

Typically, the review process comes before the editing process.

Why should I practice?

Practicing allows you to fine-tune your writing skills. The best way to practice is to consistently write. Going through the stages of drafting, revising, and editing will help you become more efficient in your writing practices and allows you to get more written content out there.

While practice does make perfect, you should be practicing perfect itself. Figure out the best process for you and practice that perfect process repeatedly until it becomes natural.