Re: GEODE-2036 and documentation practices and procedures

[Anthony Baker]

Great!  I’m much more comfortable with describing the process as CTR.

Anthony


> On Oct 26, 2016, at 12:31 PM, Karen Miller  wrote:
> 
> I would also like to add that the C-T-R model for small doc changes such as
> typo corrections
> sounds like a good model to follow.  So, +1 to that.
> 

Re: GEODE-2036 and documentation practices and procedures

[Karen Miller]

I would also like to add that the C-T-R model for small doc changes such as
typo corrections
sounds like a good model to follow.  So, +1 to that.


On Wed, Oct 26, 2016 at 10:20 AM, Karen Miller  wrote:

> Good by me to not have a catch-all JIRA.  I've made one commit under it,
> and I'll now close
> the JIRA.
>
>
> On Wed, Oct 26, 2016 at 9:36 AM, Joey McAllister 
> wrote:
>
>> 3. +1 to Anthony and Dan's recommendation not to use a catch-all JIRA.
>>
>> I think the idea was an attempt to fit within existing guidelines. If
>> there's no requirement to use a JIRA here, let's not do it.
>>
>> On Wed, Oct 26, 2016 at 9:26 AM Dave Barnes  wrote:
>>
>> > 3. If there's no hard-and-fast rule for *always* associating a JIRA with
>> > every change, then I agree with Anthony and Dan for typos and small
>> > changes.
>> >
>> > On Wed, Oct 26, 2016 at 9:19 AM, Dan Smith  wrote:
>> >
>> > > 1) +1
>> > > 2) +1
>> > >
>> > > 3)
>> > > > I don’t see much value in creating an uber-JIRA for tracking minor
>> doc
>> > > changes.  Why not skip it entirely?
>> > > I agree with Anthony on this one, there's not much value in having
>> some
>> > > catch all JIRA for unrelated changes.
>> > >
>> > > -Dan
>> > >
>> > > On Tue, Oct 25, 2016 at 7:08 PM, Anthony Baker 
>> > wrote:
>> > >
>> > > > What I _think_ you are suggesting is using C-T-R
>> (commit-then-review)
>> > [1]
>> > > > for reasonably well-defined documentation-related changes.  Do you
>> > agree?
>> > > >
>> > > > Here’s why we tag commits with a JIRA:
>> > > >
>> > > > - we can better understand the reason for a code change by looking
>> at
>> > the
>> > > > associated JIRA
>> > > > - we can scope work in/out of a release by using ‘Fix version’ on
>> the
>> > > JIRA
>> > > > - we can generate release notes by looking at resolved issues for a
>> > given
>> > > > version
>> > > >
>> > > > I don’t see much value in creating an uber-JIRA for tracking minor
>> doc
>> > > > changes.  Why not skip it entirely?
>> > > >
>> > > >
>> > > > Anthony
>> > > >
>> > > > [1] https://www.apache.org/foundation/glossary.html#CommitThenRe
>> view <
>> > > > https://www.apache.org/foundation/glossary.html#CommitThenReview>
>> > > >
>> > > >
>> > > > > On Oct 25, 2016, at 5:45 PM, Karen Miller 
>> > 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.
>> > > >
>> > > >
>> > >
>> >
>>
>
>

Re: GEODE-2036 and documentation practices and procedures

[Karen Miller]

Good by me to not have a catch-all JIRA.  I've made one commit under it,
and I'll now close
the JIRA.


On Wed, Oct 26, 2016 at 9:36 AM, Joey McAllister 
wrote:

> 3. +1 to Anthony and Dan's recommendation not to use a catch-all JIRA.
>
> I think the idea was an attempt to fit within existing guidelines. If
> there's no requirement to use a JIRA here, let's not do it.
>
> On Wed, Oct 26, 2016 at 9:26 AM Dave Barnes  wrote:
>
> > 3. If there's no hard-and-fast rule for *always* associating a JIRA with
> > every change, then I agree with Anthony and Dan for typos and small
> > changes.
> >
> > On Wed, Oct 26, 2016 at 9:19 AM, Dan Smith  wrote:
> >
> > > 1) +1
> > > 2) +1
> > >
> > > 3)
> > > > I don’t see much value in creating an uber-JIRA for tracking minor
> doc
> > > changes.  Why not skip it entirely?
> > > I agree with Anthony on this one, there's not much value in having some
> > > catch all JIRA for unrelated changes.
> > >
> > > -Dan
> > >
> > > On Tue, Oct 25, 2016 at 7:08 PM, Anthony Baker 
> > wrote:
> > >
> > > > What I _think_ you are suggesting is using C-T-R (commit-then-review)
> > [1]
> > > > for reasonably well-defined documentation-related changes.  Do you
> > agree?
> > > >
> > > > Here’s why we tag commits with a JIRA:
> > > >
> > > > - we can better understand the reason for a code change by looking at
> > the
> > > > associated JIRA
> > > > - we can scope work in/out of a release by using ‘Fix version’ on the
> > > JIRA
> > > > - we can generate release notes by looking at resolved issues for a
> > given
> > > > version
> > > >
> > > > I don’t see much value in creating an uber-JIRA for tracking minor
> doc
> > > > changes.  Why not skip it entirely?
> > > >
> > > >
> > > > Anthony
> > > >
> > > > [1] https://www.apache.org/foundation/glossary.html#CommitThenReview
> <
> > > > https://www.apache.org/foundation/glossary.html#CommitThenReview>
> > > >
> > > >
> > > > > On Oct 25, 2016, at 5:45 PM, Karen Miller 
> > 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.
> > > >
> > > >
> > >
> >
>

Re: GEODE-2036 and documentation practices and procedures

[Joey McAllister]

3. +1 to Anthony and Dan's recommendation not to use a catch-all JIRA.

I think the idea was an attempt to fit within existing guidelines. If
there's no requirement to use a JIRA here, let's not do it.

On Wed, Oct 26, 2016 at 9:26 AM Dave Barnes  wrote:

> 3. If there's no hard-and-fast rule for *always* associating a JIRA with
> every change, then I agree with Anthony and Dan for typos and small
> changes.
>
> On Wed, Oct 26, 2016 at 9:19 AM, Dan Smith  wrote:
>
> > 1) +1
> > 2) +1
> >
> > 3)
> > > I don’t see much value in creating an uber-JIRA for tracking minor doc
> > changes.  Why not skip it entirely?
> > I agree with Anthony on this one, there's not much value in having some
> > catch all JIRA for unrelated changes.
> >
> > -Dan
> >
> > On Tue, Oct 25, 2016 at 7:08 PM, Anthony Baker 
> wrote:
> >
> > > What I _think_ you are suggesting is using C-T-R (commit-then-review)
> [1]
> > > for reasonably well-defined documentation-related changes.  Do you
> agree?
> > >
> > > Here’s why we tag commits with a JIRA:
> > >
> > > - we can better understand the reason for a code change by looking at
> the
> > > associated JIRA
> > > - we can scope work in/out of a release by using ‘Fix version’ on the
> > JIRA
> > > - we can generate release notes by looking at resolved issues for a
> given
> > > version
> > >
> > > I don’t see much value in creating an uber-JIRA for tracking minor doc
> > > changes.  Why not skip it entirely?
> > >
> > >
> > > Anthony
> > >
> > > [1] https://www.apache.org/foundation/glossary.html#CommitThenReview <
> > > https://www.apache.org/foundation/glossary.html#CommitThenReview>
> > >
> > >
> > > > On Oct 25, 2016, at 5:45 PM, Karen Miller 
> 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.
> > >
> > >
> >
>

Re: GEODE-2036 and documentation practices and procedures

[Dave Barnes]

3. If there's no hard-and-fast rule for *always* associating a JIRA with
every change, then I agree with Anthony and Dan for typos and small changes.

On Wed, Oct 26, 2016 at 9:19 AM, Dan Smith  wrote:

> 1) +1
> 2) +1
>
> 3)
> > I don’t see much value in creating an uber-JIRA for tracking minor doc
> changes.  Why not skip it entirely?
> I agree with Anthony on this one, there's not much value in having some
> catch all JIRA for unrelated changes.
>
> -Dan
>
> On Tue, Oct 25, 2016 at 7:08 PM, Anthony Baker  wrote:
>
> > What I _think_ you are suggesting is using C-T-R (commit-then-review) [1]
> > for reasonably well-defined documentation-related changes.  Do you agree?
> >
> > Here’s why we tag commits with a JIRA:
> >
> > - we can better understand the reason for a code change by looking at the
> > associated JIRA
> > - we can scope work in/out of a release by using ‘Fix version’ on the
> JIRA
> > - we can generate release notes by looking at resolved issues for a given
> > version
> >
> > I don’t see much value in creating an uber-JIRA for tracking minor doc
> > changes.  Why not skip it entirely?
> >
> >
> > Anthony
> >
> > [1] https://www.apache.org/foundation/glossary.html#CommitThenReview <
> > https://www.apache.org/foundation/glossary.html#CommitThenReview>
> >
> >
> > > On Oct 25, 2016, at 5:45 PM, Karen Miller  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.
> >
> >
>

Re: GEODE-2036 and documentation practices and procedures

[Dan Smith]

1) +1
2) +1

3)
> I don’t see much value in creating an uber-JIRA for tracking minor doc
changes.  Why not skip it entirely?
I agree with Anthony on this one, there's not much value in having some
catch all JIRA for unrelated changes.

-Dan

On Tue, Oct 25, 2016 at 7:08 PM, Anthony Baker  wrote:

> What I _think_ you are suggesting is using C-T-R (commit-then-review) [1]
> for reasonably well-defined documentation-related changes.  Do you agree?
>
> Here’s why we tag commits with a JIRA:
>
> - we can better understand the reason for a code change by looking at the
> associated JIRA
> - we can scope work in/out of a release by using ‘Fix version’ on the JIRA
> - we can generate release notes by looking at resolved issues for a given
> version
>
> I don’t see much value in creating an uber-JIRA for tracking minor doc
> changes.  Why not skip it entirely?
>
>
> Anthony
>
> [1] https://www.apache.org/foundation/glossary.html#CommitThenReview <
> https://www.apache.org/foundation/glossary.html#CommitThenReview>
>
>
> > On Oct 25, 2016, at 5:45 PM, Karen Miller  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.
>
>

Re: GEODE-2036 and documentation practices and procedures

[Anthony Baker]

What I _think_ you are suggesting is using C-T-R (commit-then-review) [1] for 
reasonably well-defined documentation-related changes.  Do you agree?

Here’s why we tag commits with a JIRA:

- we can better understand the reason for a code change by looking at the 
associated JIRA
- we can scope work in/out of a release by using ‘Fix version’ on the JIRA
- we can generate release notes by looking at resolved issues for a given 
version

I don’t see much value in creating an uber-JIRA for tracking minor doc changes. 
 Why not skip it entirely?


Anthony

[1] https://www.apache.org/foundation/glossary.html#CommitThenReview 



> On Oct 25, 2016, at 5:45 PM, Karen Miller  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.

Re: GEODE-2036 and documentation practices and procedures

[Dave Barnes]

1. +1 with a guideline:

If code and docs share a JIRA ticket, the ticket cannot (or at least should
not) be closed until both parts are complete. In some cases both tasks
finish around the same time, so a shared ticket is fine.

But there are cases where code is completed before docs (as with bug fixes
where the developer doesn't realize there's a doc impact until after the
code has been repaired) or where docs finish before code (as is
historically true with deprecations). In cases where the two tasks don't
finish near the same time, I prefer separate tickets with a connection in
JIRA. This can usually take the form of a doc ticket labeled as a 'subtask'
to the code ticket. That way neither effort prevents the other from
declaring victory and moving forward.

2. +1
3. +1


On Tue, Oct 25, 2016 at 6:14 PM, William Markito 
wrote:

> 1. +1
> 2. +1  - Reason and common sense should apply...
> 3. +1
>
> On Tue, Oct 25, 2016 at 6:03 PM, Joey McAllister 
> wrote:
>
> > 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  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.
> > >
> >
>
>
>
> --
>
> ~/William
>

Re: GEODE-2036 and documentation practices and procedures

[William Markito]

1. +1
2. +1  - Reason and common sense should apply...
3. +1

On Tue, Oct 25, 2016 at 6:03 PM, Joey McAllister 
wrote:

> 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  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.
> >
>



-- 

~/William

Re: GEODE-2036 and documentation practices and procedures

[Joey McAllister]

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  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.
>

GEODE-2036 and documentation practices and procedures

[Karen Miller]

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.