Open Stack

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?
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20160509/47cf5350/attachment.html>