Page MenuHomePhabricator

GSoD 2020: Week 5
Closed, ResolvedPublic

Description

This task is a break-down of the fifth 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 5 (October 12 - 16)
  • Discuss with documentarians and find out how documentations are currently being reviewed.
  • Propose a documentation review format and discuss it with mentors and documentarians

Improve technical documentation review processes.

Currently, it's a bit hard to precisely say how technical documentations are being reviewed at Wikimedia as most of it is done informally. This isn't surprising, as documentations are Wiki's which anyone can edit, however, this doesn't mean a standardized review process for all documentations shouldn't be put in place.

Standardizing documentation review processes and properly reviewing documentations poses some advantages that would greatly improve the quality of technical documentation written. I aim at creating a standard documentation review process that would enforce a more organized way of getting feedbacks and improving newly created documentations.

Proposed documentation review process

My approach is in five basic steps to be briefly discussed below;

1) Prototype/Self review

The writer of a documentation is always the first reviewer of his own documentation, this step involves a writer thoroughly going through his own documentation and making sure it 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) Peer review (Optional)

This process involves the writer of the documentation having a colleague review the documentation for him informally, this enables the documentarian to get feedbacks from peers(who might as well be the users of the documentation) before submitting it for a proper review.

The proper review is in two stages, technical and non-technical review

3) 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.

4) 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.

5) Approval

Here, the documentation has undergone all the review processes and is published afterward.

Proposed documentation review tools

While considering what tool would be a good review tool for WMF documentations, I checked out some tools and found two that were really cool.

But all tools I found had a few problems which are listed below;

  • They aren't documentation review specific! You have to use them to author your documentations before you can use them to review it. clickhelp has a robust review system and hackmd integrates quite well with GitHub.
  • They do not support Wikitext! If at all we consider using these tools for the creation of new documentations, it is important that they support Wikitext because these documentations would reside on Mediawiki.
  • Widgets and templates cannot be used with them.
  • They have their own form of Markdown, which means WMF documentarians would have to do some extra work of learning their markdown.
  • All created documentations would reside in external webpages.

With the above stated, it becomes evident that an internal documentation review tool that integrates quite well with WMF tools and Wikitext is needed. Looking inwards, I figured out already existing tools can be used to review documentations if adequate processes are put in place.

Reviewing documentations with phabricator

Phabricator is an amazing tool that has a lot of tools that make it flexible to use. One of such tools is the workboard which is used for managing and tracking the progress of tasks. The workboard can be quite resourceful for managing how documentations are being reviewed, specifically, the Documentation workboard.

These workboards have related tasks separated into corresponding columns. We can have an entirely new column named in-review created. In this column, documentation tasks that are currently being reviewed would be placed there.

Since there are five review stages, there has to be a way to identify a task that is currently being reviewed by the review stage it is in. For this, the use of tags can come in handy, we can have tags for all review stages and these tags would be updated as the documentation progresses through each stage.

The above looks like a review process that might be in a disorderly manner, which brings the following questions to context;

  • How do documentarians know who to reach out to for a review?
  • How do they ascertain that a documentation is ready to be moved to the next stage?
  • How long should each review take?
  • Where should communication regarding the reviews take place?

To solve the above, documentarians should not be allowed to decide when a documentation is ready for the next review stage. Instead, there should be an admin or a dedicated reviewer who ascertains that these documentations has passed certain review stages and therefore moves it to the next stage. Furthermore, these admins or reviewers should be the one who does the non-technical review and decides or communicates with the technical reviewer on behalf of the documentarian.
Once a review passes all four review stages and is tagged as approved, it should be moved to the completed column.

Communication during review

When reviewing a documentation, there are two places the reviewers and the documentarians can effectively communicate.

  • Phabricator comments
  • The documentation Talk page

The above are both great and pose their own advantages, but I can't quite figure out which would be the most Ideal to use.

Having discussions on the phabricator tasks seems cool and a bit more orderly, but having it on the talk page means the readers of these documentations or future researchers can easily access the discussions on each documentation itself.

I'll do a bit more research and discuss this with the mentors as they would have more experience with both tools.

WMF documentation are Wikis!

The review process above should work quite well for newly created documentations, but how about updated documentations?

WMF documentations are often Wikis, which means anyone can improve or contribute to them. There is no Ideal way to review changes contributors make to a documentation make before they make them, but their changes can be reviewed, reverted and edited after it has been made. Hence, the author of a documentation or its reviewer should watch changes to their documentations and do well to pass it through the review process when updated.

Event Timeline

Gbahdeyboh renamed this task from GSoD 2020: Week 4 to GSoD 2020: Week 5.Oct 14 2020, 6:49 PM
Gbahdeyboh updated the task description. (Show Details)
Gbahdeyboh updated the task description. (Show Details)
Gbahdeyboh renamed this task from GSoD 2020: Week 5 to GSoD 2020: Week 5, 6 & 7.Nov 2 2020, 2:38 PM
Gbahdeyboh renamed this task from GSoD 2020: Week 5, 6 & 7 to GSoD 2020: Week 5.Nov 2 2020, 3:41 PM
Gbahdeyboh updated the task description. (Show Details)

GSoD 2020 is complete!