Open Stack

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.

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


________________________________
Rackspace Hosting Australia PTY LTD a company registered in the state of Victoria, Australia (company registered number ACN 153 275 524) whose registered office is at Level 1, 37 Pitt Street, Sydney, NSW 2000, Australia. Rackspace Hosting Australia PTY LTD privacy policy can be viewed at www.rackspace.com.au/company/legal-privacy-statement.php - This e-mail message may contain confidential or privileged information intended for the recipient. Any dissemination, distribution or copying of the enclosed material is prohibited. If you receive this transmission in error, please notify us immediately by e-mail at abuse at rackspace.com and delete the original message. Your cooperation is appreciated.