Documentation/Documentation Review Processes

Reviewing documentation

This document describes the steps and approach to reviewing updated and newly created documentation across Wikimedia projects. This document is meant to guide you through each phase of the review process.

Review processes

The documentation review processes is in three phases:

• Prototype/Self review
• Technical review
• Non-technical review

Prototype/Self review

The writer of the documentation is always its first reviewer.

This step involves a writer thoroughly going through their own documentation and making sure it follows Wikimedia's documentation style guides, formatting, methodologies, and use of language. This helps the reviewer identify their own mistakes and makes sure the documentation conforms with the style guide.

Additionally, the author of the documentation can have a colleague review the documentation for them informally, this enables the author to get feedback from peers (who might as well be the users of the documentation).

Technical review

This phase would require a subject matter expert or the team authoring the documentation to go through the documentation and check for technical accuracy, completeness of its content, and how easy it would be for new contributors to adapt. Comprehensive responses and feedback would be gotten here.

Non-technical review

The review phases above are done by the team or person who authored the document. Often, documentarians and reviewers have more knowledge of the style guides, formatting, methodologies, and use of language. Therefore, it is required that a documentarian formally review any documentation that undergoes this process. The responsibility of the documentarian will be to ascertain that the documentation conforms with Wikimedia's style guides.

Tracking review stages

Review stages are tracked using Wikimedia Phabricator and referenced on the documentation itself using the Template:Draft.

Using phabricator

This shows the life cycle of the documentation review process

The review is tracked using the Documentation Review Workboard on Phabricator. This workboard has four columns: "needs-review", "technical review", "non-technical review", and "reviewed". The review includes the following steps:

• A Phabricator task is created for a document that needs a review. The task should describe the documentation that needs a review, provide a link to it, and request for a review.
• The created task should be moved to the "needs-review" column to indicate that the task needs a review.
• A technical reviewer (can be someone you reached out to) does a technical review of this documentation. The task is moved to the "technical review" column.
• Often, for a "technical review", you would need to reach out to a reviewer yourself. The reviewer who is interested in reviewing the documentation moves it to the "technical-review" column and starts a discussion with you in the task's comment section.
• When the "technical review" is done, this task is moved to the "non-technical review" column by the reviewer.
• Once the review is done, the reviewer marks the task as "resolved" and moves it to the "reviewed" column.

Using Draft Template

Documentation that has undergone a review process or is currently being reviewed should provide some information on how it could be improved and where discussions regarding improving that documentation is being done. The draft and note templates are really useful for this use-case. If the documentation is still being developed, you should add {{ Draft }} at the top of your wikitext to indicate that the documentation is still a draft.

If a discussion around improving the documentation has started, you should change the draft to {{Note|content= Help improve the documentation on this page: Link to where improvement is being discussed }} as shown below.

 Note:

Who should use this review process?

This review process is absolutely open to everyone to use. It can be used for newly created documentation as well as documentation that is being updated.