Open Stack

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.
>>
>> 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).

This is great news! I love hearing stories like this from project teams who recognise the important of documentation. Hopefully the new model for Install Guides will help you out here, too.

> 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.

Let's work together to find out how we can help. I note that Lance Bragstad is your CPL, is that still current?

Lana

-- 
Lana Brindley
Technical Writer
Rackspace Cloud Builders Australia
http://lanabrindley.com

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 538 bytes
Desc: OpenPGP digital signature
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20160511/c79fd88f/attachment.pgp>