Open Stack

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?

I think this is fantastic and I particularly like option (2).

Thanks for this initiative.