Skip to content

Latest commit

 

History

History
53 lines (32 loc) · 2.87 KB

ContentReviewProcedures.rst

File metadata and controls

53 lines (32 loc) · 2.87 KB
Raw

Getting docs reviewed

How to swim in the deep water - A lone writer’s guide to survival

Create a content review process to:

  • facilitate consistency and accuracy across the docs (e.g., style guidelines, topic patterns)
  • communicate expectations, goals, and progress with stakeholders
  • clarify user stories, use cases, and learning objectives
  • coordinate technical reviews with SMEs

Who should review the docs?

As the lone writer, you should be the first and last person to review content before updating the docs. To confirm the accuracy of the content, set up a technical review procedure for the SMEs with knowledge of the content that you're adding or modifying. Depending on the content that you're adding or modifying, the SMEs could be people in engineering, QA, customer support, and/or marketing. You'll also want to establish a review procedure with PMs to clarify user stories, use cases, and expectations for the docs.

By the end of the content review process, the following people will have reviewed the docs:

  • you
  • PMs
  • SMEs

Creating a content review process

Below is an example content review process. You may need to modify these steps, or the order in which you carry out each step, according to your particular environment. Keep in mind that you need to learn and adapt to the processes that SMEs and other stakeholders already have in place when you begin working as a lone writer.

This procedure begins after the initial draft of a doc update:

  1. Evaluate the doc for consistency and accuracy according to style guidelines and topic patterns.
  2. Think about use cases and learning objectives for the content that you're documenting. Are these things defined well and explained properly? Can improvements be made? If you have any remaining questions, reach out to PMs to clarify and confirm objectives for the doc; SMEs can also provide valuable input to clarify user goals and learning objectives for the content that you're documenting here.
  3. Review technical information. Do you have any questions? Will users have any questions? Does the information address the use case(s)? Is there too much information? After you attempt to answer these questions, reach out to the SMEs to schedule a technical review; address any remaining questions with the SMEs at this time.
  4. Confirm that:
  • style guidelines and topic patterns are adhered to
  • user goals are clear and tasks are explained well
  • technical information is accurate

Tips for reviewing content with SMEs and PMs

Set a reasonable timeline for when the technical review is to be completed. Setting an agreed upon timeline helps keep things moving.