Re: [openstack-dev] [kolla][vote] Nit-picking documentation changes

[Michal Rostecki]

I'm late to the party and probably my mail will be meaningless. ;)

But -1 from me. Because usually I'm against "oh, nvm, fix it later" 
approaches at all. I don't see any significant problem of getting any 
kind of patches (both docs and code) merged in Kolla, especially in 
comparison to the most popular OpenStack project. I'm not even going to 
compare to the most popular open source projects. :) And I don't really 
see any problem with -1 on grammar changes if reviewer posts the proper 
spelling. Fixing such a comment takes only one minute from someone's 
life. Fixing and iterating over docs later by someone else will waste 
much more time.


Did we have some people which were actually offended by "grammar 
nitpicks" or is it some kind of assumption and effort to be 
exaggeratedly polite? Or was there any situation when reviewing any doc 
change lasted longer than two weeks?


I'm writing this as a person whose English grammar isn't perfect. And 
I'm very welcome for -1-s on my doc patches even if some minor thing is bad.


Also, abstaining from "grammar nitpicks" and fixing that stuff later by 
someone else takes away the opportunity to learn English. Feedback from 
the native speaker in real life situations can be much more valuable 
than learning any foreign language only by taking theoretical classes 
and reading text.


That said, I'm not trying to veto your decision which probably is 
obligatory now. But feel free to make an exception for me and nitpick my 
docs when I post them. ;)


__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [kolla][vote] Nit-picking documentation changes

[Kwasniewska, Alicja]

+1 to approach suggested by sdake.

Furthermore, I think it would be good if -1/0/+1 only reflects logical meaning 
of reviewed docs while still providing some suggestions on improving spelling 
and grammar in comment even if we +1 given patch.

Alicja

From: Martin André [mailto:martin.an...@gmail.com]
Sent: Wednesday, April 13, 2016 12:03 PM
To: OpenStack Development Mailing List (not for usage questions) 
<openstack-dev@lists.openstack.org>
Subject: Re: [openstack-dev] [kolla][vote] Nit-picking documentation changes


On Tue, Apr 12, 2016 at 10:05 PM, Steve Gordon 
<sgor...@redhat.com<mailto:sgor...@redhat.com>> wrote:
- Original Message -
> From: "Jeff Peeler" <jpee...@redhat.com<mailto:jpee...@redhat.com>>
> To: "OpenStack Development Mailing List (not for usage questions)" 
> <openstack-dev@lists.openstack.org<mailto:openstack-dev@lists.openstack.org>>
>
> On Mon, Apr 11, 2016 at 3:37 AM, Steven Dake (stdake) 
> <std...@cisco.com<mailto:std...@cisco.com>>
> wrote:
> > Hey folks,
> >
> > The reviewers in Kolla tend to nit-pick the quickstart guide to death
> > during
> > reviews.  I'd like to keep that high bar in place for the QSG, because it
> > is
> > our most important piece of documentation at present.  However, when new
> > contributors see the nitpicking going on in reviews, I think they may get
> > discouraged about writing documentation for other parts of Kolla.
> >
> > I'd prefer if the core reviewers held a lower bar for docs not related to
> > the philosophy or quiickstart guide document.  We can always iterate on
> > these new documents (like the operator guide) to improve them and raise the
> > bar on their quality over time, as we have done with the quickstart guide.
> > That way contributors don't feel nitpicked to death and avoid improving the
> > documentation.
> >
> > If you are a core reveiwer and agree with this approach please +1, if not
> > please –1.
>
> I'm fine with relaxing the reviews on documentation. However, there's
> a difference between having a missed comma versus the whole patch
> being littered with misspellings. In general in the former scenario I
> try to comment and leave the code review set at 0, hoping the
> contributor fixes it. The danger is that a 0 vote people sometimes
> miss, but it doesn't block progress.
My typical experience with (very) occasional drive by commits to operational 
project docs (albeit not Kolla) is that the type of nit that comes up is more 
typically -1 thanks for adding X, can you also add Y and Z. Before you know it 
a simple drive by commit to flesh out one area has become an expectation to 
write an entire chapter.

That's because you're a native speaker and you write proper English to begin 
with :)

We should be asking ourselves this simple question when reviewing documentation 
patch "does it make the documentation better?". Often the answer is yes, that's 
why I'm trying to ask for additional improvements in follow-up patches.
Regarding spelling or a grammatical mistakes, why not fix it now while it's 
still hot when we spot one in the new documentation that's being written? It's 
more time consuming to fix it later. If needed a native speaker can take over 
the patch and correct English.
Martin

-Steve

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: 
openstack-dev-requ...@lists.openstack.org?subject:unsubscribe<http://openstack-dev-requ...@lists.openstack.org?subject:unsubscribe>
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [kolla][vote] Nit-picking documentation changes

[Martin André]

On Tue, Apr 12, 2016 at 10:05 PM, Steve Gordon  wrote:

> - Original Message -
> > From: "Jeff Peeler" 
> > To: "OpenStack Development Mailing List (not for usage questions)" <
> openstack-dev@lists.openstack.org>
> >
> > On Mon, Apr 11, 2016 at 3:37 AM, Steven Dake (stdake) 
> > wrote:
> > > Hey folks,
> > >
> > > The reviewers in Kolla tend to nit-pick the quickstart guide to death
> > > during
> > > reviews.  I'd like to keep that high bar in place for the QSG, because
> it
> > > is
> > > our most important piece of documentation at present.  However, when
> new
> > > contributors see the nitpicking going on in reviews, I think they may
> get
> > > discouraged about writing documentation for other parts of Kolla.
> > >
> > > I'd prefer if the core reviewers held a lower bar for docs not related
> to
> > > the philosophy or quiickstart guide document.  We can always iterate on
> > > these new documents (like the operator guide) to improve them and
> raise the
> > > bar on their quality over time, as we have done with the quickstart
> guide.
> > > That way contributors don't feel nitpicked to death and avoid
> improving the
> > > documentation.
> > >
> > > If you are a core reveiwer and agree with this approach please +1, if
> not
> > > please –1.
> >
> > I'm fine with relaxing the reviews on documentation. However, there's
> > a difference between having a missed comma versus the whole patch
> > being littered with misspellings. In general in the former scenario I
> > try to comment and leave the code review set at 0, hoping the
> > contributor fixes it. The danger is that a 0 vote people sometimes
> > miss, but it doesn't block progress.
>
> My typical experience with (very) occasional drive by commits to
> operational project docs (albeit not Kolla) is that the type of nit that
> comes up is more typically -1 thanks for adding X, can you also add Y and
> Z. Before you know it a simple drive by commit to flesh out one area has
> become an expectation to write an entire chapter.
>

That's because you're a native speaker and you write proper English to
begin with :)

We should be asking ourselves this simple question when reviewing
documentation patch "does it make the documentation better?". Often the
answer is yes, that's why I'm trying to ask for additional improvements in
follow-up patches.

Regarding spelling or a grammatical mistakes, why not fix it now while it's
still hot when we spot one in the new documentation that's being written?
It's more time consuming to fix it later. If needed a native speaker can
take over the patch and correct English.

Martin


> -Steve
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [kolla][vote] Nit-picking documentation changes

[Vikram Hosakote (vhosakot)]

I value the friendliness and approachability that contributors seek.

I am totally fine with minor mistakes in documentation.

As they make more changes, they will understand/follow the process.

+1


Regards,
Vikram Hosakote
IRC: vhosakot

From: "Steven Dake (stdake)" >
Reply-To: "OpenStack Development Mailing List (not for usage questions)" 
>
Date: Monday, April 11, 2016 at 3:37 AM
To: "OpenStack Development Mailing List (not for usage questions)" 
>
Subject: [openstack-dev] [kolla][vote] Nit-picking documentation changes

Hey folks,

The reviewers in Kolla tend to nit-pick the quickstart guide to death during 
reviews.  I'd like to keep that high bar in place for the QSG, because it is 
our most important piece of documentation at present.  However, when new 
contributors see the nitpicking going on in reviews, I think they may get 
discouraged about writing documentation for other parts of Kolla.

I'd prefer if the core reviewers held a lower bar for docs not related to the 
philosophy or quiickstart guide document.  We can always iterate on these new 
documents (like the operator guide) to improve them and raise the bar on their 
quality over time, as we have done with the quickstart guide.  That way 
contributors don't feel nitpicked to death and avoid improving the 
documentation.

If you are a core reveiwer and agree with this approach please +1, if not 
please -1.

This is an unofficial vote and carries no commitment from the core reviewers, 
but I've included vote in the subject just to catch people's attention and to 
get folks thoughts on this matter.

Regards
-steve


__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [kolla][vote] Nit-picking documentation changes

[Steve Gordon]

- Original Message -
> From: "Jeff Peeler" 
> To: "OpenStack Development Mailing List (not for usage questions)" 
> 
> 
> On Mon, Apr 11, 2016 at 3:37 AM, Steven Dake (stdake) 
> wrote:
> > Hey folks,
> >
> > The reviewers in Kolla tend to nit-pick the quickstart guide to death
> > during
> > reviews.  I'd like to keep that high bar in place for the QSG, because it
> > is
> > our most important piece of documentation at present.  However, when new
> > contributors see the nitpicking going on in reviews, I think they may get
> > discouraged about writing documentation for other parts of Kolla.
> >
> > I'd prefer if the core reviewers held a lower bar for docs not related to
> > the philosophy or quiickstart guide document.  We can always iterate on
> > these new documents (like the operator guide) to improve them and raise the
> > bar on their quality over time, as we have done with the quickstart guide.
> > That way contributors don't feel nitpicked to death and avoid improving the
> > documentation.
> >
> > If you are a core reveiwer and agree with this approach please +1, if not
> > please –1.
> 
> I'm fine with relaxing the reviews on documentation. However, there's
> a difference between having a missed comma versus the whole patch
> being littered with misspellings. In general in the former scenario I
> try to comment and leave the code review set at 0, hoping the
> contributor fixes it. The danger is that a 0 vote people sometimes
> miss, but it doesn't block progress.

My typical experience with (very) occasional drive by commits to operational 
project docs (albeit not Kolla) is that the type of nit that comes up is more 
typically -1 thanks for adding X, can you also add Y and Z. Before you know it 
a simple drive by commit to flesh out one area has become an expectation to 
write an entire chapter.

-Steve

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [kolla][vote] Nit-picking documentation changes

[Jeff Peeler]

On Mon, Apr 11, 2016 at 3:37 AM, Steven Dake (stdake)  wrote:
> Hey folks,
>
> The reviewers in Kolla tend to nit-pick the quickstart guide to death during
> reviews.  I'd like to keep that high bar in place for the QSG, because it is
> our most important piece of documentation at present.  However, when new
> contributors see the nitpicking going on in reviews, I think they may get
> discouraged about writing documentation for other parts of Kolla.
>
> I'd prefer if the core reviewers held a lower bar for docs not related to
> the philosophy or quiickstart guide document.  We can always iterate on
> these new documents (like the operator guide) to improve them and raise the
> bar on their quality over time, as we have done with the quickstart guide.
> That way contributors don't feel nitpicked to death and avoid improving the
> documentation.
>
> If you are a core reveiwer and agree with this approach please +1, if not
> please –1.

I'm fine with relaxing the reviews on documentation. However, there's
a difference between having a missed comma versus the whole patch
being littered with misspellings. In general in the former scenario I
try to comment and leave the code review set at 0, hoping the
contributor fixes it. The danger is that a 0 vote people sometimes
miss, but it doesn't block progress.

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [kolla][vote] Nit-picking documentation changes

[Ryan Hallisey]

I'm definitely guilty of nit picking docs.  I'm fine with holding back and 
following up with a patch to fix any grammar/misspelling mistakes. +1

-Ryan  

- Original Message -
From: "Paul Bourke" <paul.bou...@oracle.com>
To: openstack-dev@lists.openstack.org
Sent: Tuesday, April 12, 2016 4:49:09 AM
Subject: Re: [openstack-dev] [kolla][vote] Nit-picking documentation changes

I've said in the past I'm not a fan of nitpicking docs. That said, I 
feel it's important for spelling and grammar to be correct. The 
quickstart guide is the first point of contact for many people to the 
project, and rightly or wrongly it will give an overall impression of 
the quality of the project.

When I review doc changes I try not to nitpick on the process being 
described - e.g. if an otherwise fine patch is already 5 iterations in 
and the example given to configure a service could be done in 3 lines 
less bash, I'll usually comment but still +2. If on the otherhand it is 
rife with typos (which by the way is easily solved with a spellchecker), 
and reads really badly I will flag it.

-Paul

On 11/04/16 19:27, Steven Dake (stdake) wrote:
> My proposal was for docs-only patches not code contributions with docs.
> Obviously we want a high bar for code contributions.  This is part of the
> reason we have the DocImpact flag (for folks that don't feel comfortable
> writing documentation because perhaps of ESL, or other reasons).
>
> We already have a way to decouple code from docs with DocImpact.
>
> Regards
> -steve
>
> On 4/11/16, 6:17 AM, "Michał Jastrzębski" <inc...@gmail.com> wrote:
>
>> So one way to approach it is to decouple docs from code, make it 2
>> reviews. We can -1 code without docs and ask to create separate
>> patchset depending on one in question with docs. Then we can nitpick
>> all we want:) new contributor will get his/hers code merged, at least
>> one patchset, so it will work better on morale, and we'll be able to
>> keep high bar for QSG and other docs. There is possibility that author
>> will leave docs patch after code merge, but well, we can take over
>> docs review.
>>
>> What do you think guys? I'd really like to keep high quality standard
>> all the way and don't scare off new commiters at the same time.
>>
>> Cheers,
>> Michal
>>
>> On 11 April 2016 at 03:50, Steven Dake (stdake) <std...@cisco.com> wrote:
>>>
>>>
>>> On 4/11/16, 1:38 AM, "Gerard Braad" <m...@gbraad.nl> wrote:
>>>
>>>> Hi,
>>>>
>>>> On Mon, Apr 11, 2016 at 4:20 PM, Steven Dake (stdake) <std...@cisco.com>
>>>> wrote:
>>>>> On 4/11/16, 12:54 AM, "Gerard Braad" <m...@gbraad.nl> wrote:
>>>>> as
>>>>>> at the moment getting an environment up-and-running according to the
>>>>>> quickstart guide is a hit and miss
>>>>> I don't think deployment is not hit or miss as long as the QSG are
>>>>> followed to a T :)
>>>>
>>>> Maybe saying "at the moment" was incorrect. As the deployment
>>>> according to the QSG has been a few weeks ago. Sorry about this... as
>>>> you guys have put a lot of effort into it recently.
>>>>
>>>>
>>>>> I agree we need more clarity in what belongs in the QSG.
>>>> This can be a separate discussion (Not intending to hijack this thread).
>>>>
>>>>
>>>> I am not a core reviewer, but I keep it as-is. I do not see a need for
>>>
>>> Even though your not a core reviewer, your comments are valued.  The
>>> reason I addressed core reviewers specifically as they have +2
>>> permissions
>>> and I would like more leniency on new documentation in other files
>>> outside
>>> those listed above (philosophy document, QSG) with a pubic statement of
>>> such.
>>>
>>>> a lower-bar. Although, documentation is the entry-point into a
>>>> community (as user and potential contributor) and therefore it should
>>>> be of a high quality. Maybe I would be to provide more suggestions
>>>> instead of just indication of 'change this for that'.
>>>
>>> The issue I see with our QSG is it has the highest bar for review
>>> passage
>>> of any file in the repository.  Any QSG change typically requires 10 or
>>> more patch sets to make it through the core reviewer gauntlet.  This
>>> discourages people from writing new documentation.  I don't want this to
>>> carry over into other parts of the documentation that are as of

Re: [openstack-dev] [kolla][vote] Nit-picking documentation changes

[Paul Bourke]

I've said in the past I'm not a fan of nitpicking docs. That said, I 
feel it's important for spelling and grammar to be correct. The 
quickstart guide is the first point of contact for many people to the 
project, and rightly or wrongly it will give an overall impression of 
the quality of the project.


When I review doc changes I try not to nitpick on the process being 
described - e.g. if an otherwise fine patch is already 5 iterations in 
and the example given to configure a service could be done in 3 lines 
less bash, I'll usually comment but still +2. If on the otherhand it is 
rife with typos (which by the way is easily solved with a spellchecker), 
and reads really badly I will flag it.


-Paul

On 11/04/16 19:27, Steven Dake (stdake) wrote:

My proposal was for docs-only patches not code contributions with docs.
Obviously we want a high bar for code contributions.  This is part of the
reason we have the DocImpact flag (for folks that don't feel comfortable
writing documentation because perhaps of ESL, or other reasons).

We already have a way to decouple code from docs with DocImpact.

Regards
-steve

On 4/11/16, 6:17 AM, "Michał Jastrzębski"  wrote:


So one way to approach it is to decouple docs from code, make it 2
reviews. We can -1 code without docs and ask to create separate
patchset depending on one in question with docs. Then we can nitpick
all we want:) new contributor will get his/hers code merged, at least
one patchset, so it will work better on morale, and we'll be able to
keep high bar for QSG and other docs. There is possibility that author
will leave docs patch after code merge, but well, we can take over
docs review.

What do you think guys? I'd really like to keep high quality standard
all the way and don't scare off new commiters at the same time.

Cheers,
Michal

On 11 April 2016 at 03:50, Steven Dake (stdake)  wrote:



On 4/11/16, 1:38 AM, "Gerard Braad"  wrote:


Hi,

On Mon, Apr 11, 2016 at 4:20 PM, Steven Dake (stdake) 
wrote:

On 4/11/16, 12:54 AM, "Gerard Braad"  wrote:
as

at the moment getting an environment up-and-running according to the
quickstart guide is a hit and miss

I don't think deployment is not hit or miss as long as the QSG are
followed to a T :)


Maybe saying "at the moment" was incorrect. As the deployment
according to the QSG has been a few weeks ago. Sorry about this... as
you guys have put a lot of effort into it recently.



I agree we need more clarity in what belongs in the QSG.

This can be a separate discussion (Not intending to hijack this thread).


I am not a core reviewer, but I keep it as-is. I do not see a need for


Even though your not a core reviewer, your comments are valued.  The
reason I addressed core reviewers specifically as they have +2
permissions
and I would like more leniency on new documentation in other files
outside
those listed above (philosophy document, QSG) with a pubic statement of
such.


a lower-bar. Although, documentation is the entry-point into a
community (as user and potential contributor) and therefore it should
be of a high quality. Maybe I would be to provide more suggestions
instead of just indication of 'change this for that'.


The issue I see with our QSG is it has the highest bar for review
passage
of any file in the repository.  Any QSG change typically requires 10 or
more patch sets to make it through the core reviewer gauntlet.  This
discourages people from writing new documentation.  I don't want this to
carry over into other parts of the documentation that are as of yet
unwritten.  I'd like new documentation to be ok with misspellings,
grammar
errors, formatting problems, ESL authors, and that sort of thing.

The QSG should tolerate none of these types of errors at this point - it
must be absolutely perfect (at least in English:) as to not cause
confusion to new operators.

Regards
-steve



regards,


Gerard


__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe:
openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev




_
_
OpenStack Development Mailing List (not for usage questions)
Unsubscribe:
openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev



__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: 

Re: [openstack-dev] [kolla][vote] Nit-picking documentation changes

[Steven Dake (stdake)]

My proposal was for docs-only patches not code contributions with docs.
Obviously we want a high bar for code contributions.  This is part of the
reason we have the DocImpact flag (for folks that don't feel comfortable
writing documentation because perhaps of ESL, or other reasons).

We already have a way to decouple code from docs with DocImpact.

Regards
-steve

On 4/11/16, 6:17 AM, "Michał Jastrzębski"  wrote:

>So one way to approach it is to decouple docs from code, make it 2
>reviews. We can -1 code without docs and ask to create separate
>patchset depending on one in question with docs. Then we can nitpick
>all we want:) new contributor will get his/hers code merged, at least
>one patchset, so it will work better on morale, and we'll be able to
>keep high bar for QSG and other docs. There is possibility that author
>will leave docs patch after code merge, but well, we can take over
>docs review.
>
>What do you think guys? I'd really like to keep high quality standard
>all the way and don't scare off new commiters at the same time.
>
>Cheers,
>Michal
>
>On 11 April 2016 at 03:50, Steven Dake (stdake)  wrote:
>>
>>
>> On 4/11/16, 1:38 AM, "Gerard Braad"  wrote:
>>
>>>Hi,
>>>
>>>On Mon, Apr 11, 2016 at 4:20 PM, Steven Dake (stdake) 
>>>wrote:
 On 4/11/16, 12:54 AM, "Gerard Braad"  wrote:
 as
>at the moment getting an environment up-and-running according to the
>quickstart guide is a hit and miss
 I don't think deployment is not hit or miss as long as the QSG are
 followed to a T :)
>>>
>>>Maybe saying "at the moment" was incorrect. As the deployment
>>>according to the QSG has been a few weeks ago. Sorry about this... as
>>>you guys have put a lot of effort into it recently.
>>>
>>>
 I agree we need more clarity in what belongs in the QSG.
>>>This can be a separate discussion (Not intending to hijack this thread).
>>>
>>>
>>>I am not a core reviewer, but I keep it as-is. I do not see a need for
>>
>> Even though your not a core reviewer, your comments are valued.  The
>> reason I addressed core reviewers specifically as they have +2
>>permissions
>> and I would like more leniency on new documentation in other files
>>outside
>> those listed above (philosophy document, QSG) with a pubic statement of
>> such.
>>
>>>a lower-bar. Although, documentation is the entry-point into a
>>>community (as user and potential contributor) and therefore it should
>>>be of a high quality. Maybe I would be to provide more suggestions
>>>instead of just indication of 'change this for that'.
>>
>> The issue I see with our QSG is it has the highest bar for review
>>passage
>> of any file in the repository.  Any QSG change typically requires 10 or
>> more patch sets to make it through the core reviewer gauntlet.  This
>> discourages people from writing new documentation.  I don't want this to
>> carry over into other parts of the documentation that are as of yet
>> unwritten.  I'd like new documentation to be ok with misspellings,
>>grammar
>> errors, formatting problems, ESL authors, and that sort of thing.
>>
>> The QSG should tolerate none of these types of errors at this point - it
>> must be absolutely perfect (at least in English:) as to not cause
>> confusion to new operators.
>>
>> Regards
>> -steve
>>
>>>
>>>regards,
>>>
>>>
>>>Gerard
>>>
>>>
>>>__
>>>OpenStack Development Mailing List (not for usage questions)
>>>Unsubscribe: 
>>>openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
>>>http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>>
>>
>> 
>>_
>>_
>> OpenStack Development Mailing List (not for usage questions)
>> Unsubscribe: 
>>openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>__
>OpenStack Development Mailing List (not for usage questions)
>Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
>http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [kolla][vote] Nit-picking documentation changes

[Michał Jastrzębski]

So one way to approach it is to decouple docs from code, make it 2
reviews. We can -1 code without docs and ask to create separate
patchset depending on one in question with docs. Then we can nitpick
all we want:) new contributor will get his/hers code merged, at least
one patchset, so it will work better on morale, and we'll be able to
keep high bar for QSG and other docs. There is possibility that author
will leave docs patch after code merge, but well, we can take over
docs review.

What do you think guys? I'd really like to keep high quality standard
all the way and don't scare off new commiters at the same time.

Cheers,
Michal

On 11 April 2016 at 03:50, Steven Dake (stdake)  wrote:
>
>
> On 4/11/16, 1:38 AM, "Gerard Braad"  wrote:
>
>>Hi,
>>
>>On Mon, Apr 11, 2016 at 4:20 PM, Steven Dake (stdake) 
>>wrote:
>>> On 4/11/16, 12:54 AM, "Gerard Braad"  wrote:
>>> as
at the moment getting an environment up-and-running according to the
quickstart guide is a hit and miss
>>> I don't think deployment is not hit or miss as long as the QSG are
>>> followed to a T :)
>>
>>Maybe saying "at the moment" was incorrect. As the deployment
>>according to the QSG has been a few weeks ago. Sorry about this... as
>>you guys have put a lot of effort into it recently.
>>
>>
>>> I agree we need more clarity in what belongs in the QSG.
>>This can be a separate discussion (Not intending to hijack this thread).
>>
>>
>>I am not a core reviewer, but I keep it as-is. I do not see a need for
>
> Even though your not a core reviewer, your comments are valued.  The
> reason I addressed core reviewers specifically as they have +2 permissions
> and I would like more leniency on new documentation in other files outside
> those listed above (philosophy document, QSG) with a pubic statement of
> such.
>
>>a lower-bar. Although, documentation is the entry-point into a
>>community (as user and potential contributor) and therefore it should
>>be of a high quality. Maybe I would be to provide more suggestions
>>instead of just indication of 'change this for that'.
>
> The issue I see with our QSG is it has the highest bar for review passage
> of any file in the repository.  Any QSG change typically requires 10 or
> more patch sets to make it through the core reviewer gauntlet.  This
> discourages people from writing new documentation.  I don't want this to
> carry over into other parts of the documentation that are as of yet
> unwritten.  I'd like new documentation to be ok with misspellings, grammar
> errors, formatting problems, ESL authors, and that sort of thing.
>
> The QSG should tolerate none of these types of errors at this point - it
> must be absolutely perfect (at least in English:) as to not cause
> confusion to new operators.
>
> Regards
> -steve
>
>>
>>regards,
>>
>>
>>Gerard
>>
>>__
>>OpenStack Development Mailing List (not for usage questions)
>>Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
>>http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [kolla][vote] Nit-picking documentation changes

[Steven Dake (stdake)]

On 4/11/16, 1:38 AM, "Gerard Braad"  wrote:

>Hi,
>
>On Mon, Apr 11, 2016 at 4:20 PM, Steven Dake (stdake) 
>wrote:
>> On 4/11/16, 12:54 AM, "Gerard Braad"  wrote:
>> as
>>>at the moment getting an environment up-and-running according to the
>>>quickstart guide is a hit and miss
>> I don't think deployment is not hit or miss as long as the QSG are
>> followed to a T :)
>
>Maybe saying "at the moment" was incorrect. As the deployment
>according to the QSG has been a few weeks ago. Sorry about this... as
>you guys have put a lot of effort into it recently.
>
>
>> I agree we need more clarity in what belongs in the QSG.
>This can be a separate discussion (Not intending to hijack this thread).
>
>
>I am not a core reviewer, but I keep it as-is. I do not see a need for

Even though your not a core reviewer, your comments are valued.  The
reason I addressed core reviewers specifically as they have +2 permissions
and I would like more leniency on new documentation in other files outside
those listed above (philosophy document, QSG) with a pubic statement of
such.

>a lower-bar. Although, documentation is the entry-point into a
>community (as user and potential contributor) and therefore it should
>be of a high quality. Maybe I would be to provide more suggestions
>instead of just indication of 'change this for that'.

The issue I see with our QSG is it has the highest bar for review passage
of any file in the repository.  Any QSG change typically requires 10 or
more patch sets to make it through the core reviewer gauntlet.  This
discourages people from writing new documentation.  I don't want this to
carry over into other parts of the documentation that are as of yet
unwritten.  I'd like new documentation to be ok with misspellings, grammar
errors, formatting problems, ESL authors, and that sort of thing.

The QSG should tolerate none of these types of errors at this point - it
must be absolutely perfect (at least in English:) as to not cause
confusion to new operators.

Regards
-steve

>
>regards,
>
>
>Gerard
>
>__
>OpenStack Development Mailing List (not for usage questions)
>Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
>http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [kolla][vote] Nit-picking documentation changes

[Gerard Braad]

Hi,

On Mon, Apr 11, 2016 at 4:20 PM, Steven Dake (stdake)  wrote:
> On 4/11/16, 12:54 AM, "Gerard Braad"  wrote:
> as
>>at the moment getting an environment up-and-running according to the
>>quickstart guide is a hit and miss
> I don't think deployment is not hit or miss as long as the QSG are
> followed to a T :)

Maybe saying "at the moment" was incorrect. As the deployment
according to the QSG has been a few weeks ago. Sorry about this... as
you guys have put a lot of effort into it recently.


> I agree we need more clarity in what belongs in the QSG.
This can be a separate discussion (Not intending to hijack this thread).


I am not a core reviewer, but I keep it as-is. I do not see a need for
a lower-bar. Although, documentation is the entry-point into a
community (as user and potential contributor) and therefore it should
be of a high quality. Maybe I would be to provide more suggestions
instead of just indication of 'change this for that'.

regards,


Gerard

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [kolla][vote] Nit-picking documentation changes

[Steven Dake (stdake)]

On 4/11/16, 12:54 AM, "Gerard Braad"  wrote:

>Hi Steven,
>
>On Mon, Apr 11, 2016 at 3:37 PM, Steven Dake (stdake) 
>wrote:
>> However, when new
>> contributors see the nitpicking going on in reviews, I think they may
>>get
>> discouraged about writing documentation for other parts of Kolla.
>
>This is one of the things I experienced myself and this thought had
>crossed my mind. Although, the high expectation is understandable as
>at the moment getting an environment up-and-running according to the
>quickstart guide is a hit and miss. This is of course not directly
>related to the guide itself (or is it?), but possible issues in code
>stability.

Gerard,

I believe the QSG is in pretty good shape.  We have been suffering some
serious code churn when we moved to docker 1.10 and kolla-docker module.
These were both highly positive changes, but destabilized he code base a
bit - blocking development for nearly 2 weeks during m3 (iirc).  We have
also had a lot of code churn related to upgrade, reconfigure, and drop
root features which were again highly positive but partially disruptive as
well.

I don't think deployment is not hit or miss as long as the QSG are
followed to a T :)

>
>Although, I think we need to be more clear about what needs to be in
>the Quickstart guide. Is a mult-node environment something we need to
>discuss or is this for another document? What about common issues and
>error codes that can be addressed?

I agree we need more clarity in what belongs in the QSG.  At Tokyo summit
we held a documentation session where we produced an outline of what the
documentation should be.  We didn't define scope or boundaries on the
documentation outline, nor did we define review expectations.  I am open
to anyone from the community putting together an outline with scope and
boundaries as a review in the specs directory so we can iterate on what
exactly should go where and what the code review expectations are.

Regards,
-steve


>
>regards,
>
>
>Gerard
>
>-- 
>Gerard Braad — 吉拉德
>   F/OSS & IT Consultant in Beijing
>   http://gbraad.nl  gpg: 0x592CFE7
>
>__
>OpenStack Development Mailing List (not for usage questions)
>Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
>http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [kolla][vote] Nit-picking documentation changes

[Gerard Braad]

Hi Steven,

On Mon, Apr 11, 2016 at 3:37 PM, Steven Dake (stdake)  wrote:
> However, when new
> contributors see the nitpicking going on in reviews, I think they may get
> discouraged about writing documentation for other parts of Kolla.

This is one of the things I experienced myself and this thought had
crossed my mind. Although, the high expectation is understandable as
at the moment getting an environment up-and-running according to the
quickstart guide is a hit and miss. This is of course not directly
related to the guide itself (or is it?), but possible issues in code
stability.

Although, I think we need to be more clear about what needs to be in
the Quickstart guide. Is a mult-node environment something we need to
discuss or is this for another document? What about common issues and
error codes that can be addressed?

regards,


Gerard

-- 
Gerard Braad — 吉拉德
   F/OSS & IT Consultant in Beijing
   http://gbraad.nl  gpg: 0x592CFE7

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev