Open Stack

On Tue, May 10, 2016 at 12:40 AM, Matt Kassawara <mkassawara at gmail.com>
wrote:

> At each summit, I speak with a variety of developers from different
> projects about the apparent lack of contributions to the central
> documentation. At previous summits, the most common complaint involved
> using DocBook. After converting most of the documentation to RST, the most
> common complaint at the recent summit involves the review process,
> particularly the lengthy amount of time patches sit in the review queue
> with -1s for various "conventions" problems such as structure, formatting,
> grammar, spelling, etc. Unlike most OpenStack developers that focus on a
> particular project, the documentation team covers all projects and lacks
> the capacity to understand each one enough to contribute and maintain
> technically accurate documentation in a timely manner. However, covering
> all projects enables the documentation team to organize and present the
> documentation to various audiences, primarily operators and users, that
> consume OpenStack as a coherent product. In other words, the entire process
> relies on developers contributing to the central documentation. So, before
> developer frustrations drive some or all projects to move their
> documentation in-tree which which negatively impacts the goal of presenting
> a coherent product, I suggest establishing an agreement between developers
> and the documentation team regarding the review process.
>
> As much as the documentation team wants to present OpenStack as a coherent
> product, it contains many projects with different contribution processes.
> In some cases, individual developers prefer to contribute in unique ways.
> Thus, the conventional "one-size-fits-all" approach that the documentation
> team historically takes with reviewing contributions from developers yields
> various levels of frustration among projects and developers. I ran a
> potential solution by various developers during the recent summit and
> received enough positive feedback to discuss it with a larger audience. So,
> here goes...
>
> A project or individual developer decides the level of documentation team
> involvement with reviewing patches. The developer adds a WIP to the
> documentation patch while adding content to prevent premature reviews by
> the documentation team. Once the content achieves a sufficient level of
> technical accuracy, the developer removes the WIP and adds a comment in the
> review indicating of the following preferences:
>
> 1) The documentation team should review the patch for compliance with
> conventions (proper structure, format, grammar, spelling, etc.) and provide
> feedback to the developer who updates the patch.
> 2) The documentation team should modify the patch to make it compliant and
> ask the developer for a final review to prior to merging it.
> 3) The documentation team should only modify the patch to make it build
> (if necessary) and quickly merge it with a documentation bug to resolve any
> compliance problems in a future patch by the documentation team.
>
> What do you think?
>

+1 to the second option!

In most cases it's faster and easier just to patch your suggestions rather
than comment -> wait for the response -> check again. Just less talk, more
action...

Olga


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


-- 
Best regards,
Olga Gusarenko

Technical Writer | Mirantis, Kharkiv | 38, Lenin av., Kharkiv, Ukraine
ogusarenko at mirantis.com | skype: gusarenko.olga
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20160512/bf75cee2/attachment.html>