On Tue, May 10, 2016 at 12:40 AM, 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? > +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-requ...@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 ogusare...@mirantis.com | skype: gusarenko.olga
__________________________________________________________________________ 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
