<div dir="ltr">I'm also not a fan of option 3 because it trades one kind of technical debt for another. However, one could argue that some (relevant) content is better than no (or defunct) content. Interestingly, option 3 also reflects what ultimately happens if projects decide to maintain all documentation in their respective repositories. Easier for developers to contribute, but at the expense of usability by our various audiences.</div><div class="gmail_extra"><br><div class="gmail_quote">On Thu, May 12, 2016 at 6:56 AM, Brian Curtin <span dir="ltr"><<a href="mailto:brian@python.org" target="_blank">brian@python.org</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div class="HOEnZb"><div class="h5">On Thu, May 12, 2016 at 1:24 AM, Joseph Robinson<br>
<<a href="mailto:joseph.robinson@rackspace.com">joseph.robinson@rackspace.com</a>> wrote:<br>
> Hi All, One reply inline:<br>
><br>
> On 11/05/2016, 7:33 AM, "Lana Brindley" <<a href="mailto:openstack@lanabrindley.com">openstack@lanabrindley.com</a>> wrote:<br>
><br>
>>On 10/05/16 20:08, Julien Danjou wrote:<br>
>>> 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>
>>> 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>
>>><br>
>>>> 1) The documentation team should review the patch for compliance with<br>
>>>> conventions (proper structure, format, grammar, spelling, etc.) and<br>
>>>>provide<br>
>>>> feedback to the developer who updates the patch.<br>
>>>> 2) The documentation team should modify the patch to make it compliant<br>
>>>>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<br>
>>>>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>
> I like the idea of options 2 and 3. Specifically though, I think Option 3<br>
> - merging content that builds, and checking out a bug to improve the<br>
> quality - can work in some cases. With a dedicated teams on several<br>
> guides, docs contributors would be able to pick up bugs right away -<br>
> that¹s my 2c.<br>
<br>
</div></div>This is just enabling technical debt as process and ultimately hurts<br>
the users of the docs who end up with poorly worded or incorrect<br>
information by letting subpar -- but syntactically correct --<br>
documentation in. Even a dedicated team isn't going to get around to<br>
everything, and someone coming in later to pick up bugs to document is<br>
less likely to be the right person to convey the proper explanation<br>
and details than the one who implemented the work.<br>
<div class="HOEnZb"><div class="h5"><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>
</div></div></blockquote></div><br></div>