This thread is created to discuss how we can create a quality review process on documentation.
This is the process that I followed when working on documentation related tasks on Trello.
Pick up a task from Trello
Started working on the documentation task in a google doc, and after completing the task give the public review access
Shared it in the Trello
Created a talk thread regarding the task so that others can give their feedback
Finalize the content and add that to Wiki.
I also have another idea for this process.
Restrict the access for a limited number of people (for the people who created and lastly updated)
If anyone willing to contribute can follow the process above.
Once the content is finalized in the google doc, edit access request should be made to the admins of the intended page.
Once the permission given, necessary changes can be made to the relevant wiki page/ pages.
This is my personal idea and it’s open to discussion, there can be issues when limiting the edit access for a limited number of members.
At the same time,we can add a checklist or similar thing to maintain the consistency among multiple documentation sources available. For example: If a member wants to edit the OpenMRS SDK installation, the trello card can be made with a checklist of options as follows.
Necessary changes done to Wiki
Necessary changes done to gitBook
So the Trello card can be moved to completed section when both the changes are done. I hope this can help to maintain consistency, but there can be issues which are open to discussion.
When we come up with a good process we can update the process as a SOP in the volunteer guide for technical writers.
Thanks for sharing this @uthpala and any other ideas are welcome.We shall be having a discussion around this on our next documentation call on Tuesday.
as we somewhat discussed that this method can lead to people being blockers if the review process gets delayed , so maybe instead of waiting for an approval we could give people access to edit the wiki but there could be something like a single verified version for a wiki (I have less idea how will this get implemented though ),I think that way we would be able to handle both issues well, avoiding blockers and maintaining desirable quality in the docs
Let us do a thing @saurabh@uthpala.
Like I think we should keep everything what was decided in the meeting and to face the blocker issue which @saurabh pointed out. We can do that let us put labels on the things which needs approval.
Like “Highest Priority”, “Low Priority” etc.
It will help the reviews to keep a check on everything and the updates with high priority can be reviewed quickly.
The level of priority can be decided by the fact that how wrong was the previous information on the page was.
Like if the previous information on the wiki page was too wrong and could misguide the contributors then it can get the “Highest Priority” tag. Similarly other things can be given tags.
As per the discussion on last call I have summarized the quality review process as follows.
Pick up a task from the Trello Up Next section. The respective reviewers for the documentation task is added by the person who created the task.
Started working on the task
These tasks can be categorized as high priority and low priority where categorization can be added and updated:
By the person who created the card.
By the person who work on it
By the person who review it
If the document needs more feedback and guidance follow the below procedure.
Work on the task using a google document and give the comment access for the public.
Then the technical writer can create a separate thread, attach the document to it and tag the respective reviewers to the thread.
After the review, publish the document and attach the link of the page that changes are done along with a summary of changes done to the Trello card.
If the task does not need any guidance , directly work on the task, notify the watchers about what the
changes are and publish it. Then attach the link of the page that changes done along with a
summary of changes done to the Trello card.
Important:
High priority: Installation guidelines, Drastic document changes
Low priority: styling fixes, Content alignments and positioning.
Kindly comment if anything needs to improve of if anything that I have missed. Thanks
),I think that way we would be able to handle both issues well, avoiding blockers and maintaining desirable quality in the docs 