Open Stack

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 --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 800 bytes
Desc: not available
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20160510/4f2ec2f7/attachment.pgp>