Reviewing documentation pull requests

[Cheetham, Anastasia]

On 2014-06-02, at 2:06 PM, Colin Clark wrote:

> Note that we could, if we thought it was worthwhile, create a set of suggestions and recommendations for the documentation team to follow, rather than a formalized, all-or-nothing process. I can imagine those recommendations would include something to the effect of “unless the changes are small, documentation committers should themselves submit them as pull requests and ask for peer review,” without requiring this to be formalized.

I like this approach. There will certainly be scenarios where someone on the docs team is just cleaning up docs, fixing formatting, tweaking, etc. In these kinds of scenarios, a pull request and review seems unnecessary. On the other hand, if someone is documenting new functionality, a review would ensure that a second set of eyes checks the docs for clarity, working links, etc. before it goes in. This ensure that most docs will have a second look before they get in, but maintaining (as opposed to creating) is a bit simpler.

-- 
Anastasia Cheetham     Inclusive Design Research Centre
acheetham at ocadu.ca           Inclusive Design Institute
                                        OCAD University