Open Stack

On 04/06/2015 07:39 PM, Anne Gentle wrote:
> Hi all,
>
> You may have read on the openstack-dev list that I don't plan to run for
> Docs PTL. [1] So far, Lana Brindley has announced her candidacy. [2]
> We're all looking for leadership from specialty teams and individuals.
> During all these transitions, we need to over-communicate and maintain
> trust with each other. I'm writing to emphasize this need again.
>
> We've had two patches recently that want to put deliverables into
> openstack-manuals without a blueprint in place that explains the
> justification for the placement. I'm not blaming or shaming here, I just
> want to point out what needs to happen going forward.
>
> Please write a spec and link it to a blueprint, get that spec and
> blueprint approved before proposing the patch. We need to up our level
> of communication now more than ever for a couple of reasons. First,
> centralized coordination is especially crucial during the transition
> period of a new docs PTL. Second, as the project listings grow, our
> centralized resources need to be applied strategically.
>
> I know you all will work hard for this release, for the centralized doc
> team needs, and to make sure we all communicate astoundingly well. Let's
> not lose momentum going into this high-activity release period.

Thanks Anne for writing this! Yes, with the speciality teams we're 
experimenting with growing the contributor base and that's very 
important. As somebody that is working on our tools and reviewing much, 
I feel that we currently undercommunicate. ;(
We have to figure out how we can continue to align with each other on 
some aspects. It's important to share plans and that includes 
expectations, deadlines and modus operandi.

Let's take one step back and look at the broader picture of what we're 
doing with documentation:

We have in OpenStack at least two types of documentation:
* (Developer) documentation for a specific project
* Common documentation handled by the documentation team

One definition for common documentation is documentation that covers 
multiple OpenStack projects targeted for a specific use case. The goal 
of common documentation is to deliver content that complements each 
other and not duplicates.

For the common documentation, the following is shared:
* A common docs team and PTL
* Conventions on how to write
* Conventions on how to use markup
* Tools for building the documentation
* For some documents and tools, we share repositories and thus reviews

For all documentation on docs.openstack.org and developer.openstack.org 
- so for both types of documentation -, we share also a common design 
based on the OpenStack branding.

So, how can we communicate better about what's happening and align
so that we're not lously coupled islands with small teams but a great
docs team that strives for great documentation?

Btw. I know that teams meet but cannot attend all meetings myself. I
see for some meetings, like the Networking Meeting often minutes and
highly appreciate those! Thanks, Nick! Also, Anne's "What's up docs?" is 
highly appreciated.

I agree with Anne that blueprints and specs - and the discussion around 
them - are crucial!

Do you have further specific ideas for better planning and communication?

Andreas
-- 
  Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
   SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
    GF: Felix Imendörffer, Jane Smithard, Jennifer Guild, Dilip Upmanyu,
        Graham Norton, HRB 21284 (AG Nürnberg)
     GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126