Thanks for kicking this off, Karen! 1. +1 - I like the idea of making documentation part of the requirements for issues that need it. Is it better in these cases to use the primary ticket or to create a new subticket associated with the primary one?
2. +1 - I agree that reviews should be on a case-by-case basis. Since the community has committers/contributors who specialize in technical documentation, I'd hope that those docs specialists would make themselves available for such reviews. And, on the flip side, I'd hope that anyone focused on adding/editing documentation based on new/changed code would seek the review of the developer who worked on the code. And, yes (connected to #3 below), I think small changes might not need reviews at all. 3. +1 On Tue, Oct 25, 2016 at 5:47 PM Karen Miller <kmil...@apache.org> wrote: > With our documentation now in the same repository as the code, there are > now > some doc-related issues that could use some community consensus. Here are > some of my opinions to start the discussion. > > 1. Create new JIRA tickets for each documentation task, or use the existing > ticket under > which the code is committed for the documentation task? > > I'd like to see a combination of both, but use the existing ticket > wherever > possible. By using the same ticket as the code, the documentation effort is > less > likely to be forgotten. I certainly think that when a new property is > introduced, > or a default value is changed, the same ticket can be used. > > I think that for large, and new efforts (in the documentation), new > tickets are the > way to go. > > 2. Do we need a review effort for all documentation tasks? > > My opinion: no, not for everything. The bigger the changes, the more > likely that > a review is warranted. > > 3. Do we need a new JIRA ticket for each very little documentation change? > > On this question, my strong opinion is no, we don't need distinct JIRAs. > I'd like to propose that we use a single ticket per release that > all typo fixes and really small changes are committed under. No > reviews needed. We won't end up with dozens of tickets, each for a tiny > change that really needs no community discussion. If the ticket becomes > abused, > we can revisit the topic. > > I've already created https://issues.apache.org/jira/browse/GEODE-2036 > for > just this purpose, as I have a typo that I want to fix. If no one objects, > we can > use this ticket for all tiny fixes that go with Geode 1.1.0. >
