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

Paul Bourke paul.bourke at oracle.com
Tue Apr 12 08:49:09 UTC 2016


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" <inc007 at 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) <stdake at cisco.com> wrote:
>>>
>>>
>>> On 4/11/16, 1:38 AM, "Gerard Braad" <me at gbraad.nl> wrote:
>>>
>>>> Hi,
>>>>
>>>> On Mon, Apr 11, 2016 at 4:20 PM, Steven Dake (stdake) <stdake at cisco.com>
>>>> wrote:
>>>>> On 4/11/16, 12:54 AM, "Gerard Braad" <me at 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 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-request at 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-request at 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-request at 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-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>



More information about the OpenStack-dev mailing list