[openstack-dev] [doc][ptls][all] Documentation publishing future

Ildiko Vancsa ildiko.vancsa at gmail.com
Tue May 23 15:05:06 UTC 2017

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

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.


More information about the OpenStack-dev mailing list