Open Stack

On Fri, Oct 3, 2014 at 8:18 PM, Zane Bitter <zbitter at redhat.com> wrote:

> Amidst all the discussion about layers and tents there has been this
> lurking issue about Docs and their need to prioritise work that we haven't
> really done a deep dive on yet. I'd like to start that discussion by
> summarising my understanding of the situation, and hopefully Anne and
> others can jump in and tell me what I've gotten horribly wrong.
>
> AIUI back in the day, all of the documentation for OpenStack was handled
> in a centralised way by the Docs team. We can all agree that doesn't scale,
> and that was recognised early on during the project's expansion.
>
> The current system is something of a hybrid model - for some subset of
> official projects considered "important", the Docs team is directly
> responsible; for the others, the project team has to write the
> documentation. The docs team is available to provide support and tools for
> other official projects.
>
>
I think the Docs team isn't directly responsible for any project; we work
with all projects.


> It's not clear how "important" is currently defined... one suspects it's
> by date of accession ;)
>
>
There's more and more docs coverage in the common docs repos the longer a
project has been around, but that's not always due to "doc team only" work.

This wiki page attempts to describe current integrating/incubating
processing for docs.
https://wiki.openstack.org/wiki/Documentation/IncubateIntegrate

Thing is, it's tough to say that any given project has completed docs. Nova
still probably has the lead with the most doc bugs since Xen is barely
documented and there are a lot of doc bugs for the Compute API versions. So
it's possible to measure with our crude instruments and even with those
measurements, inner chewy center projects could be called under-documented.


> The prospect of a much larger tent with many more projects in
> OpenStack-proper shines a spotlight on the scalability of the Docs team,
> and in particular how they decide which projects are "important" to work on
> directly.
>
> There seems to be an implicit argument floating around that there are a
> bunch of projects that depend on each other and we need to create a
> governance structure around blessing this, rather than merely observing it
> as an emergent property of the gate, at least in part because that's the
> only way to tell the Docs team what is "important".
>
> There are two problems with this line of thought IMHO. The obvious one is
> of course that the number of bi-directional dependencies of a project is
> not *in any way* related to how important it is to have documentation for
> it. It makes about as much sense as saying that we're only going to
> document projects whose names contain the letter 't'.
>
> The second is that it implies that the Docs team are the only people in
> OpenStack who need the TC to tell them what to work on. Developers
> generally work on what they or their employer feels is important. If you
> see something being neglected you either try to help out or pass the word
> up that more resources are needed in a particular area. Is there any reason
> to think it wouldn't work the same with technical writers? Is anyone
> seriously worried that Nova will go undocumented unless the TC creates a
> project structure that specifically calls it out as important?
>
> What I'm envisioning is that we would move to a completely distributed
> model, where the documentation for each project is owned by that project.
> People who care about the project being documented would either work on it
> themselves and/or recruit developers and/or technical writers to do so. The
> Docs program itself would concentrate on very high-level
> non-project-specific documentation and on standards and tools to help
> deliver a consistent presentation across projects. Of course we would
> expect there to be considerable overlap between the people contributing to
> the Docs program itself and those contributing to documentation of the
> various projects. Docs would also have a formal liaison program to ensure
> that information is disseminated rapidly and evenly.
>
>
I still maintain the thinking that common OpenStack docs are very valuable
and the information architecture across projects could only go so far to
truly serve users.

Here's my current thinking and plan of attack on multiple fronts. Oh, that
analogy is so militaristic, I'd revise more peacefully but ... time. :)

1. We need better page-based design and navigation for many of our docs.
I'm working with the Foundation on a redesign. This may include simpler
source files.
2. We still need book-like output. Examples of books include the
Installation Guides, Operations Guide, the Security Guide, and probably the
Architecture Design Guide. Every other bit of content can go into pages if
we have decent design, information architecture, navigation, and
versioning. Except maybe the API reference [0], that's a special beast.
3. We need better maintenance and care of app developer docs like the API
Reference. This also includes simpler source files.

Of course it's not just "these three things" but we sure can do a lot
towards more scaling across multiple projects. While maintaining quality
and speed. Oh the impossible. :)


> Is there any part of this that folks don't think would work? How many
> projects could it scale to? Is there a reason we need the TC to bless a
> subset of projects, or is it reasonable to expect that individual docs
> contributors can select what is most important to work on in much the same
> way that most contributors do?
>
>
Yes, this self-selection happens already. The stats for the last six months
show over 200 docs contributors in the docs repos, but still about 10
people work on "all" OpenStack docs. I believe in the "long tail" [1] of
doc contribution because no one can know all of OpenStack.


> I know there are a lot of subtleties of which I have hitherto remained
> blissfully ignorant. Let's get those out in the open and get to the bottom
> of what impact, if any, the docs scaling issue needs to have on our
> governance structure.
>
>
It's not just docs scaling, it's the question of how you can meet the
end-goal of why you document anything anyway -- supporting users of many
types. So on one end of a spectrum you would have "Apache Foundation" style
docs - each project does what ever they want and tools and styles how they
want. On the other side you'd have "only official trademark-able docs are
allowed on docs.openstack.org" (which is nearly where we are since the
trademark questions are still being worked).

In between we have some gains from central coordination, shared audiences
and segmentation, cross-purpose re-use of common documentation, shared
toolsets and shared goals like increasing adoption and supporting tested
solutions through documentation. We're somewhere in this middle because
we're working very hard with a focused group to produce high-quality
documentation through community and collaborative means.

Thanks for writing up your thoughts Zane - glad to know we're all noodling
on this together.

Anne

[0] http://developer.openstack.org/api-ref.html
[1] http://en.wikipedia.org/wiki/Long_tail


> cheers,
> Zane.
>
>
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20141003/7fa4b3d4/attachment.html>