Matt Kassawara <mkassaw...@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. __________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
