Hey, Good conversation. So I think we should explore these two positions a little bit. The question here, I think, is whether or not we want to introduce a formal governance model for our documentation repository.
As background, our current formal process for making changes to critical code repositories (in this case, Infusion) requires that: 1. All changes be submitted via a pull request 2. Someone on the committers team—specifically, someone who isn’t the person making the change--must thoroughly review and push all changes 3. A pull request should be reviewed by someone with experience in the part of the code that was changed There are many reasons why we follow this formal approach when it comes to source code. The key reasons relate to the fact that changes to code carry the risk of causing: * Regressions in the software’s functionality * Errors in the new functionality * Maintainability problems * Performance problems So our formal commit process is intended to strike a balance between ensuring stability and making it easy to improve. Since the risk of problems is so high with code, we’re willing to wait on new features until they have been carefully reviewed by one or more committers. We rely more on process because the risk is very high. This process, as we know, can be slow sometimes. In the case of our documentation, we should ask ourselves a couple of questions. First, do changes to documentation represent a similar risk? Can a documentation change: * Be inaccurate? * Break other parts of the documentation? * Cause the documentation to become significantly harder to maintain? * Cause the documentation to become significantly harder to use? My impression is that these issues are indeed a concern, but perhaps to a lesser extent than with code. So then the question is, given the risk, do we want to trade off ease of improvement for correctness by introducing a formal process? 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’d like to hear your thoughts, Justin and Antranig (and other members of the documentation team), on these questions. Colin On Jun 2, 2014, at 1:07 PM, Justin Obara <[email protected]> wrote: > I'd argue that it would be a good opportunity to ensure correctness, as well > as proper presentation and readability, of our documentation by reviewing it > before it made it's way up to master. > > Thanks > Justin > > On Jun 2, 2014, at 11:26 AM, Antranig Basman <[email protected]> > wrote: > >> I think that we had agreed that those with commit access to the >> documentation would be able to to push/merge changes without formality. This >> preserves the existing semantic that we have for edits made to our old >> documentation in the wiki. I believe this is the model Colin is referring to >> by the "simple and open process". >> >> Cheers, >> Antranig >> >> On 02/06/2014 14:05, Justin Obara wrote: >>> I agree that the committers for Infusion-Docs should not necessarily be the >>> same as those for Infusion. We should probably keep to a similar branch, >>> pull request, merge (with logs) workflow. >>> >>> Thanks >>> Justin >>> >>> On May 30, 2014, at 4:55 PM, Colin Clark <[email protected]> wrote: >>> >>>> Hi Anastasia and all, >>>> >>>> I think it’s worthwhile to have a lightweight code review process for >>>> documentation pull requests. I’ve enjoyed following the way you’ve all >>>> been working so far. I think it would be great to ensure a member of our >>>> documentation working group reviews pull requests as they come in, and >>>> recruit the developers who worked on a particular feature to also lend a >>>> hand with the documentation review process. >>>> >>>> In my opinion, and this is open to debate, the people who can edit and >>>> review and push documentation changes to our documentation repo need not >>>> be committers to the Infusion repository—we should have a more simple and >>>> open process for this. I believe we can create a distinct team in Github >>>> to enable more open push access to the repo if we desire. >>>> >>>> Thoughts? >>>> >>>> Colin >>>> >>>> On May 12, 2014, at 11:59 AM, Cheetham, Anastasia <[email protected]> >>>> wrote: >>>> >>>>> >>>>> Michelle, Simon and Antranig, >>>>> >>>>> We've been making great progress porting documentation to markdown. We're >>>>> now faced with the question of who reviews pull requests for >>>>> documentation. We never really discussed this. >>>>> >>>>> Does anyone have any thoughts on this? >>>>> >>>>> -- >>>>> Anastasia Cheetham Inclusive Design Research Centre >>>>> [email protected] Inclusive Design Institute >>>>> OCAD University >>>>> >>>>> _______________________________________________________ >>>>> fluid-work mailing list - [email protected] >>>>> To unsubscribe, change settings or access archives, >>>>> see http://lists.idrc.ocad.ca/mailman/listinfo/fluid-work >>>> >>>> _______________________________________________________ >>>> fluid-work mailing list - [email protected] >>>> To unsubscribe, change settings or access archives, >>>> see http://lists.idrc.ocad.ca/mailman/listinfo/fluid-work >>> >>> _______________________________________________________ >>> fluid-work mailing list - [email protected] >>> To unsubscribe, change settings or access archives, >>> see http://lists.idrc.ocad.ca/mailman/listinfo/fluid-work >>> >> >> _______________________________________________________ >> fluid-work mailing list - [email protected] >> To unsubscribe, change settings or access archives, >> see http://lists.idrc.ocad.ca/mailman/listinfo/fluid-work > > _______________________________________________________ > fluid-work mailing list - [email protected] > To unsubscribe, change settings or access archives, > see http://lists.idrc.ocad.ca/mailman/listinfo/fluid-work _______________________________________________________ fluid-work mailing list - [email protected] To unsubscribe, change settings or access archives, see http://lists.idrc.ocad.ca/mailman/listinfo/fluid-work
