Open Stack

On 廿十七年五月廿四日 朝 09:38, Rochelle Grober wrote:
>   From: Ildiko
>   > On 2017. May 23., at 15:43, Sean McGinnis <sean.mcginnis at gmx.com>
>> wrote:
>>>
>>> On Mon, May 22, 2017 at 05:50:50PM -0500, Anne Gentle wrote:
>>>> On Mon, May 22, 2017 at 5:41 PM, Sean McGinnis
>>>> <sean.mcginnis at gmx.com>
>>>> wrote:
>>>>
>>>>>
>>>>> [snip]
>>>>>
>>>>
>>>> Hey Sean, is the "right to merge" the top difficulty you envision
>>>> with 1 or 2? Or is it finding people to do the writing and reviews?
>>>> Curious about your thoughts and if you have some experience with
>>>> specific day-to-day behavior here, I would love your insights.
>>>>
>>>> Anne
>>>
>>> I think it's more about finding people to do the writing and reviews,
>>> though having incentives like having more say in that area of things
>>> could be beneficial for finding those people.
>>
>> I think it is important to note here that by having the documentation (in it’s
>> easily identifiable, own folder) living together with the code in the same
>> repository you have the developer(s) of the feature as first line candidates
>> on adding documentation to their change.
>>
>> I know that writing good technical documentation is it’s own profession, but
>> having the initial data there which can be fixed by experienced writers if
>> needed is a huge win compared to anything separated, where you might not
>> have any documentation at all.
>>
>> So by having the ability to -1 a change because of the lack of documentation
>> is on one hand might be a process change for reviewers, but gives you the
>> docs contributors as well.
> 
> Possible side benefits here:  If a new, wannabe developer starts with the docs to figure out how to participate in the project, they may/will (if encouraged) file bugs against the docs where they are wrong or lacking.  Beyond that, if the newbie is reading the code s/he may just fix some low hanging fruit docs issues, or even go deeper.  I know, devs don't read docs, but I think they sneak looks when they think no one is looking.  And then get infuriated if the docs don't match the code.  Perusers of code have more time to address issues than firefighters (fixing high priority bugs), so it's possible that this new approach will encourage more complete documentation.  I can be optimistic, too.

+1, contributing to documentation should be a much easier starting point 
than code & a good way to learn the gerrit workflow. If the doc patch 
coming in from the newbie is "better than what's there", it should be 
merged swiftly.

> 
> --Rocky
>   
>> So to summarize, the changes what Alex described do not indicate that the
>> core team has to write the documentation themselves or finding a team of
>> technical writers before applying the changes, but be conscious about caring
>> whether docs is added along with the code changes.
>>
>> Thanks,
>> Ildikó
>>
>>
>>
>> __________________________________________________________
>> ________________
>> 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
>