Open Stack

Julien,

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.

On Tue, May 10, 2016 at 4:08 AM, Julien Danjou <julien at danjou.info> 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.
> >
> > What do you think?
>
> We, Telemetry, are moving our documentation in-tree and are applying a
> policy of "no doc, no merge" (same policy we had for unit tests).
> So until the doc team starts to help projects with that (proof-reading,
> pointing out missing doc update in patches, etc) and trying to be part
> of actual OpenStack projects, I don't think your goal will ever work.
>
> For example, we have an up-to-date documentation in Gnocchi since the
> beginning, that covers the whole project. It's probably not coherent
> with the rest of OpenStack in wording etc, but we'd be delighted to have
> some folks of the doc team help us with that.
>
> Cheers,
> --
> Julien Danjou
> /* Free Software hacker
>    https://julien.danjou.info */
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20160510/3b61e10c/attachment.html>