[openstack-dev] [all][docs][tc] How to scale Documentation

Zane Bitter zbitter at redhat.com
Sat Oct 4 01:18:43 UTC 2014

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.

It's not clear how "important" is currently defined... one suspects it's 
by date of accession ;)

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.

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?

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.


More information about the OpenStack-dev mailing list