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.
cheers,
Zane.
_______________________________________________
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
