Open Stack

On Thu, May 12, 2016 at 1:24 AM, Joseph Robinson
<joseph.robinson at rackspace.com> wrote:
> Hi All, One reply inline:
>
> On 11/05/2016, 7:33 AM, "Lana Brindley" <openstack at lanabrindley.com> wrote:
>
>>On 10/05/16 20:08, Julien Danjou wrote:
>>> On Mon, May 09 2016, Matt Kassawara wrote:
>>>
>>>> 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.
>>>
>>> My 2c, but it's said all over the place that OpenStack is not a product,
>>> but a framework. So perhaps the goal you're pursuing is not working
>>> because it's not accessible by design?
>>>
>>>> 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.
>
> I like the idea of options 2 and 3. Specifically though, I think Option 3
> - merging content that builds, and checking out a bug to improve the
> quality - can work in some cases. With a dedicated teams on several
> guides, docs contributors would be able to pick up bugs right away -
> that¹s my 2c.

This is just enabling technical debt as process and ultimately hurts
the users of the docs who end up with poorly worded or incorrect
information by letting subpar -- but syntactically correct --
documentation in. Even a dedicated team isn't going to get around to
everything, and someone coming in later to pick up bugs to document is
less likely to be the right person to convey the proper explanation
and details than the one who implemented the work.