I’ve tried various methods for content review. Most of them suck. After someone gave me a 40 page Word doc with various columns listing doc URLs, headings, and comments about what to change, I decided to do something different – I implemented the Github pull request workflow for doc reviews.
I put my content in a private Github repo and created a branch called “review.” Then I added a button on each page of my docs that pointed to the corresponding source page for that topic. Clicking the button takes the person directly to the Github source page in the review branch.
I also added my reviewers as collaborators to the project so they could edit directly on the branch (instead of forking the entire project, as you would need to do if you’re not a project collaborator).
I told the reviewer to just add comments in brackets with her initial at the beginning.
So far it’s working pretty well. I periodically check out the review branch and make all the changes from the reviewer. When finished, I create a pull request to merge the review branch into the master.
In general, during the review period I work in the review branch as well. I don’t want to enter merge conflict hell by making lots of updates to the master branch while reviewers are adding a ton of contents in the review branch.
Right now I just have one thorough reviewer for the project. For others who just give me 2 line comments in emails, this method is overkill so I just continue with email threads for those types of reviewers.
The Github branching approach is more common in software development projects. I think it will work well enough for content review. The main benefit is tying the comment to the page the user is viewing. With the previous Word doc review method, the comments were mapped to the source like spaghetti spilled on the floor.
I’m curious to know if others have used this method for doc reviews. I’m also deliberating with using Bitbucket instead of Github. Our devs us hg instead of git, so it might be a better fit for version control consistency.