<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Tue, May 10, 2016 at 12:40 AM, Matt Kassawara <span dir="ltr"><<a href="mailto:mkassawara@gmail.com" target="_blank">mkassawara@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr">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. <div><br></div><div>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...</div><div><br></div><div>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:</div><div><br></div><div>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.</div><div>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.</div><div>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.</div><div><br></div><div>What do you think?</div></div></blockquote><div><br></div><div>+1 to the second option!<br><br></div><div>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...<br><br></div><div>Olga<br></div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>__________________________________________________________________________<br>
OpenStack Development Mailing List (not for usage questions)<br>
Unsubscribe: <a href="http://OpenStack-dev-request@lists.openstack.org?subject:unsubscribe" rel="noreferrer" target="_blank">OpenStack-dev-request@lists.openstack.org?subject:unsubscribe</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" rel="noreferrer" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
<br></blockquote></div><br><br clear="all"><br>-- <br><div class="gmail_signature"><div dir="ltr"><div><div dir="ltr"><div><div dir="ltr"><div><div dir="ltr"><div><div dir="ltr"><div><div dir="ltr"><div><div dir="ltr"><div><div dir="ltr"><div><div><span style="color:rgb(102,102,102)">Best regards,<br></span></div><span style="color:rgb(102,102,102)">Olga Gusarenko<br><br></span></div><span style="color:rgb(102,102,102)">Technical Writer<span><span> | Mirantis, Kharkiv | 38, Lenin av., Kharkiv, Ukraine<br></span></span></span><div><span style="color:rgb(102,102,102)"><a href="mailto:ogusarenko@mirantis.com" target="_blank">ogusarenko@mirantis.com</a> <span><span>| </span></span>skype: gusarenko.olga<span><span></span></span><span><span></span></span></span></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div>
</div></div>