<div dir="ltr"><div><span style="line-height:1.5">On 09/05/16 22:57, Matt Kassawara wrote:</span><br></div><div>> At each summit, I speak with a variety of developers from different</div><div>> projects about the apparent lack of contributions to the central</div><div>> documentation. At previous summits, the most common complaint involved</div><div>> using DocBook. After converting most of the documentation to RST, the</div><div>> most common complaint at the recent summit involves the review</div><div>> process, particularly the lengthy amount of time patches sit in the</div><div>> review queue with -1s for various "conventions" problems such as</div><div>> structure, formatting, grammar, spelling, etc. Unlike most OpenStack</div><div>> developers that focus on a particular project, the documentation team</div><div>> covers all projects and lacks the capacity to understand each one</div><div>> enough to contribute and maintain technically accurate documentation</div><div>> in a timely manner. However, covering all projects enables the</div><div>> documentation team to organize and present the documentation to</div><div>> various audiences, primarily operators and users, that consume</div><div>> OpenStack as a coherent product. In other words, the entire process</div><div>> relies on developers contributing to the central documentation. So,</div><div>> before developer frustrations drive some or all projects to move their</div><div>> documentation in-tree which which negatively impacts the goal of</div><div>> presenting a coherent product, I suggest establishing an agreement</div><div>> between developers and the documentation team regarding the review</div><div>> process. </div><div>></div><div>> As much as the documentation team wants to present OpenStack as a</div><div>> coherent product, it contains many projects with different</div><div>> contribution processes. In some cases, individual developers prefer to</div><div>> contribute in unique ways. Thus, the conventional "one-size-fits-all"</div><div>> approach that the documentation team historically takes with reviewing</div><div>> contributions from developers yields various levels of frustration</div><div>> among projects and developers. I ran a potential solution by various</div><div>> developers during the recent summit and received enough positive</div><div>> feedback to discuss it with a larger audience. So, here goes...</div><div>></div><div>> A project or individual developer decides the level of documentation</div><div>> team involvement with reviewing patches. The developer adds a WIP to</div><div>> the documentation patch while adding content to prevent premature</div><div>> reviews by the documentation team. Once the content achieves a</div><div>> sufficient level of technical accuracy, the developer removes the WIP</div><div>> and adds a comment in the review indicating of the following preferences:</div><div>></div><div>> 1) The documentation team should review the patch for compliance with</div><div>> conventions (proper structure, format, grammar, spelling, etc.) and</div><div>> provide feedback to the developer who updates the patch.</div><div>> 2) The documentation team should modify the patch to make it compliant</div><div>> 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</div><div>> build (if necessary) and quickly merge it with a documentation bug to</div><div>> resolve any compliance problems in a future patch by the documentation</div><div>> team.</div><div>></div><div>> What do you think?</div><div><br></div><div>I have mixed feelings about this.  I have contributed documentation in</div><div>the past, and felt frustrated by the level of pickiness of the reviews -</div><div>to the extent of being somewhat demotivated about contributing more doc</div><div>improvements and additions.  So I think I understand where this</div><div>conversation is arising from.</div><div><br></div><div>On the other hand, firstly I like some of the pickiness, e.g. I don't</div><div>really want to see our docs littered with spelling mistakes - so it</div><div>might just be that I'm being subjective about what I think is good and</div><div>bad pickiness; and secondly I think we should acknowledge that this</div><div>isn't only a documentation issue: I've had 'could you also clean this up</div><div>while you're in the area' comments, and comments that seem to ask for</div><div>things just because they can, rather than being properly argued or</div><div>clearly beneficial, for code changes just as much as for docs.</div><div><br></div><div>On balance, though, and given that IMO we are still lacking a lot of</div><div>important OpenStack documentation (or documentation structure), I think</div><div>it would be good for documentation reviewers to adjust their bar down</div><div>slightly, so as to encourage more contributions.</div><div><br></div><div>I'm not sure if that needs the detailed solution proposed above; it</div><div>should be enough for the team to agree an adjusted approach among</div><div>themselves.</div><div><br></div><div>Regards,</div><div>    Neil</div><div><br></div></div>