<div dir="ltr">Julien,<div><br></div><div>Project or framework... regardless of the word, consumers of OpenStack (without additional knowledge) see it as a single entity. Anyway, especially after implementing the big tent, the documentation team is not large enough to assign one or more people to manage documentation in each project repository (including bug triage and patch reviews) or attend project meetings. As a result, the documentation team asks each project to assign a liaison that advocates documentation with developers, assists developers with contributing/maintaining documentation, and collaborates with the documentation team. Collaboration includes bug triage, patch reviews, attending meetings, and communicating via IRC and/or the mailing list. Unfortunately, most projects do not collaborate effectively with the documentation team which results in a disconnection between the documentation team and projects/developers. Improving collaboration via liaisons would resolve most problems.</div></div><div class="gmail_extra"><br><div class="gmail_quote">On Tue, May 10, 2016 at 4:08 AM, Julien Danjou <span dir="ltr"><<a href="mailto:julien@danjou.info" target="_blank">julien@danjou.info</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><span class="">On Mon, May 09 2016, Matt Kassawara wrote:<br>
<br>
> So, before developer frustrations drive some or all projects to move<br>
> their documentation in-tree which which negatively impacts the goal of<br>
> presenting a coherent product, I suggest establishing an agreement<br>
> between developers and the documentation team regarding the review<br>
> process.<br>
<br>
</span>My 2c, but it's said all over the place that OpenStack is not a product,<br>
but a framework. So perhaps the goal you're pursuing is not working<br>
because it's not accessible by design?<br>
<span class=""><br>
> 1) The documentation team should review the patch for compliance with<br>
> conventions (proper structure, format, grammar, spelling, etc.) and provide<br>
> feedback to the developer who updates the patch.<br>
> 2) The documentation team should modify the patch to make it compliant and<br>
> ask the developer for a final review to prior to merging it.<br>
> 3) The documentation team should only modify the patch to make it build (if<br>
> necessary) and quickly merge it with a documentation bug to resolve any<br>
> compliance problems in a future patch by the documentation team.<br>
><br>
> What do you think?<br>
<br>
</span>We, Telemetry, are moving our documentation in-tree and are applying a<br>
policy of "no doc, no merge" (same policy we had for unit tests).<br>
So until the doc team starts to help projects with that (proof-reading,<br>
pointing out missing doc update in patches, etc) and trying to be part<br>
of actual OpenStack projects, I don't think your goal will ever work.<br>
<br>
For example, we have an up-to-date documentation in Gnocchi since the<br>
beginning, that covers the whole project. It's probably not coherent<br>
with the rest of OpenStack in wording etc, but we'd be delighted to have<br>
some folks of the doc team help us with that.<br>
<br>
Cheers,<br>
<span class="HOEnZb"><font color="#888888">--<br>
Julien Danjou<br>
/* Free Software hacker<br>
   <a href="https://julien.danjou.info" rel="noreferrer" target="_blank">https://julien.danjou.info</a> */<br>
</font></span></blockquote></div><br></div>