Focused on documentation review

In my first blog I gave you some hints on writing good documentation. In this blog, I would like to talk about good practices and what should be taken into account during the review process.

Some people may ask why is it important to review documentation? Well, the answer is to find errors and missing information in the content. During review, we can often identify issues also in the software. There is no such thing as a perfect documentation, there is always a room for improvement. If you are interested, let’s get to it!

When planning a project, you should allocate enough time to allow for reviewing and testing the documentation. Especially in agile environment; you can plan also regular reviews of smaller parts of documentation. It is up to you. The following picture shows a simplified documentation process as we do it at Davinci.

In connection with the documentation review process, we need to take the following into account:

1.   People are busy

Well, people are usually busy with other tasks. Some of them may consider reviewing documentation a necessary evil and sending them a request to review documents can be perceived as piling up. Anyway, it is good to find time to allow for a detailed documentation review.

 

2.   Deadline must be set

If you send the document to a reviewer, make sure, you state a clear deadline. The reviewers must know how they should review and when is the deadline. If you want them to send you feedback via email, or use track changes in MS Word, let them know beforehand. If there are no rules or agreement on the process, the review can take much more time and it won’t be very effective.

 

3.   Who should review?

In general, a person with deep knowledge of the software does the review. It is usually a Product Owner or a Project Manager. However, developers, testers or other team members are good reviewers as well. If you plan to let an independent person do the review, e.g. a colleague from another team, I suggest not to do it. Such person cannot find minor issues and do a thorough review. Rather involve a colleague with an independent view during the testing phase of the documentation process (see the image above) to check the accuracy of the information.

 

4.   Choose the right approach

Imagine, you receive feedback from multiple reviewers in several documents (multiple versions of the reviewed document). For example, comments_John, comments_John_Jack, v2_Jack, v2final_Jack. It will cost the writer too much time to incorporate all comments to create a final document. It is a good practice to only work on one version of the document. Choose an approach that will help you simplify the review process and deliver the final document in the most efficient way. There are many ways how reviewers can deliver their feedback e.g. via email, track changes in MS Word, comments in PDF, online collaboration etc. Find what works the best for you.

 

5.   Feedback must be effective

So that the documentation process is quick and smooth, it is important to give useful feedback. Let’s say, you receive a reviewed document with these comments: “This isn’t clear.”, “Uhm?”, “What are you trying to say?”. These types of comments are usually not very useful and can result in time-consuming discussion. So, what can we do to improve our feedback? As a reviewer, start by asking yourself why you have such feelings or reactions to that paragraph or screen capture. Is the paragraph too long or too short? Are there multiple main ideas combined in one paragraph? Is the chapter out of logical flow? If you find the source of your negative feelings, you will be able to add valuable comments.

Example:

Useless comment: Something is missing here.
Useful comment:  The filtering options may be a little bit tricky. Explain them in more detail.

 

First aid kit for reviewers

If you struggle with reviews, use a checklist that can help you. There are some review checklists available on the internet; e.g. on techwhirl.com. If you use company template to meet the defined look & feel, you probably don’t have to waste time with review of formatting. In my opinion, the most important things you need to check are these:

  • Does the application work according to the documentation?
  • Is the documentation structure clear?
  • Are all process steps accurate?
  • Are screen captures accurate?
  • Is all the information easy to read and use?

If you manage to answer “YES” to all these questions at the end of the review process, you should be safe.

 

As you can see, if you follow these simple recommendations, you'll be safe on your way to a more effective review process. So, choose the right reviewer, set a clear deadline, decide on a good review approach and send your document for a review.

Happy reviewing.

 

Publikované: 09. aug 2017 13:41
  • Anna Longauerová

    Document Writer

    Anna sa v Davinci software naplno venuje tvorbe používateľských príručiek. Okrem písania má rada aj japončinu, decoupage a iné tvorivé činnosti.

We want you

Do you see yourself working with us? Check out our vacancies. Is your ideal vacancy not in the list? Please send an open application. We are interested in new talents, both young and experienced.

Join us

Podobné články