Open Stack

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.

On Thu, May 12, 2016 at 6:56 AM, Brian Curtin <brian at python.org> wrote:

> 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.
>
> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20160512/435297a6/attachment.html>