This task is a break-down of the sixth and seventh week of GSoD based on the timeline T255360: GSoD 2020 Proposal: Improving Wikimedia's onboarding processes and documentation standards
Related tasks for other weeks can be found here T262918: GSoD 2020
Week 6 - 7 (October 19 - 30)
- Revise the proposed format based on feedbacks gotten from mentors and documentarians.
- Create a document guide explaining the finalized format discussed in depth.
- Discuss how the format documented can be enforced on documentarians and across all Wikimedia documentations.
Last week, I proposed a documentation review process and explained how tools like phabricator can be leveraged on for documentation reviews.
This week, I'll be focusing more on revising the suggested process based on feedbacks gotten, I will be making adjustments where necessary. But firstly, I would like to restructure the five review processes into something less verbose.
Revised review process
The documentation review process has been revised into 3 basic processes after which documentations would only be approved after all processes have been undergone.
1) Prototype/Self review
The writer of a documentation is always the first reviewer of their own documentations, therefore, a documentarian is obligated to review and do a copy editing of his documentation before submitting it for review.
As a part of this step, the documentarian is allowed to share the documentation with a friend or colleagues.
The documentarian is to make sure that the documentation follows Wikimedia's documentation style guides, formatting, methodologies, and use of language. This helps the reviewer identify his own mistakes and makes sure the documentation conforms with the style guide. Additionally, new documentation tasks are to be created by strictly following this guide.
2) Technical Review
This phase would require a senior colleague 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 feedbacks would be gotten here.
3) Non-technical Review
Here, the documentation has been checked for technical accuracy and correctness and it's time to ascertain that the style guides, formatting, methodologies, and use of language were strictly followed. This would be done by an experienced reviewer who is more familiar with these guides.
Documentations would only be moved out of the review phase if all and only if all review stages has been passed.
Phabricator as a documentation review tool
Phabricators workboard can be very resourceful for reviewing documentations, here is a detailed summary of how it can be used.
Workboards are divided into columns, with each column containing related tasks.
- A new column for documentations that are currently reviewed will be created on the workboard. This column will be named in-review.
- A new task will be created for all documentation that needs a review, the task would describe what the documentation is about and provide a link to it.
- All newly created documentation review tasks will have a tag named needs-review, and will be added to the in-review column on the documentation workboard.
- A tag will be used to identify the review stage a documentation is currently in. There will be 3 tags namely;
- prototype review
- technical review
- non-technical review.
- A documentation that has passed all review stages will be moved to the Completed column on the documentation workboard.
The need for a documentation review admin.
The described structure and review workflow above further creates more questions like;
- How do people find documentation that needs a review?
- Who decides who is to review a documentation?
- Who decides when a documentation is fit to move to the next review stage, and who moves it?
- How do documentarians find the right reviewers for their newly created documentation?
- etc
The idea of a review admin is to have someone who will oversee the entire review life cycle of a documentation.
The review admin will be responsible for;
- Making sure a newly created documentation has a review task created for it on phabricator
- The newly created task has the needs-review tag which indicates that the documentation needs a reviewer
- The task is moved to the in-review column on the documentation workboard.
- Contact Engineers and documentarians who would do the review of the documentation and also oversee and partake in this review process.
- Occasionally do the non-technical review phase of a documentation.
- Determine when a documentation is fit to be moved from one review stage to another.
Identifying documentations in review
Documentations are not created on phabricator, therefore there has to be a way to identify documentations that are being reviewed currently, that have been reviewed, or that needs a review.
For this purpose, templates can come in really handy. There is a ( {{ Draft }} ) template for documentations that are currently in development, I think this should be maintained.
Then we will need to create new templates, one for in-review and another for reviewed.
The meaning of both templates is immediately obvious, the first will be used for documentations that have passed the development phase and are currently being reviewed, while the other will be used to identify documentations that have been reviewed and published.
Documentation review life-cycle
The below is a flow chart showing the review life-cycle of a documentation.
Feature requests
Phabricator and Mediawiki aren't documentation review tools, therefore, using them to review a documentation would most certainly come with some setback. One of such setback is fostering effective communication between the reviewer and the documentarian. While it's true that phabricator and discuss pages can be used for effectively communicating, they might not be the best option for reviewing a documentation.
Proposing Review Issues
When a reviewer goes through a document and finds a phrase, sentence, or line he would like to change, seek more clarification on, or ask a question about. He should not have to go to phabricator to type out the phrase just so he could reference it. Rather, he should be able to highlight that phrase or sentence and create a discussion thread for it. This discussion thread is called a review issue.
This can pose a lot of advantages to how documentations are being reviewed, all the discussion to any specific sentence being reviewed will reside in one single place and are automatically referenced.
Issues should have the following features;
- When reviewing a document, all highlighted text that has an associated issue should have their background colored. When you click on any of them, the discussion thread of that issue should be displayed.
- Issues should be sharable, which means there should be a share button that generates a sharable link to that issue.
- Issues should be resolvable. After a series of discussions on any issue thread, the reviewer should be able to mark the issue has resolved.
- Reviewer should be able to highlight a sentence or phrase and suggest a better sentence or phrase.
- The documentarian should be able to view the reviewers suggestions and approve it or start a discussion thread on it.
Todo
- Include a section that helps people understand what types of documention this review process would be a great fit for.
- Prototype/Technical reviews should be done by the writer, teams, or group who wrote the document
- review-admin should do only as much work a necessary.