<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Fri, Oct 3, 2014 at 8:18 PM, Zane Bitter <span dir="ltr"><<a href="mailto:zbitter@redhat.com" target="_blank">zbitter@redhat.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">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.<br>
<br>
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.<br>
<br>
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.<br>
<br></blockquote><div><br></div><div>I think the Docs team isn't directly responsible for any project; we work with all projects.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
It's not clear how "important" is currently defined... one suspects it's by date of accession ;)<br>
<br></blockquote><div><br></div><div>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. </div><div><br></div><div>This wiki page attempts to describe current integrating/incubating processing for docs. <a href="https://wiki.openstack.org/wiki/Documentation/IncubateIntegrate">https://wiki.openstack.org/wiki/Documentation/IncubateIntegrate</a></div><div><br></div><div>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.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
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.<br>
<br>
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".<br>
<br>
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'.<br>
<br>
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?<br>
<br>
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.<br>
<br></blockquote><div><br></div><div>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. </div><div><br></div><div>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. :) </div><div><br></div><div>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.</div><div>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.</div><div>3. We need better maintenance and care of app developer docs like the API Reference. This also includes simpler source files.</div><div><br></div><div>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. :)  </div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
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?<br>
<br></blockquote><div><br></div><div>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.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
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.<br>
<br></blockquote><div><br></div><div>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 <a href="http://docs.openstack.org">docs.openstack.org</a>" (which is nearly where we are since the trademark questions are still being worked). </div><div><br></div><div>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. </div><div><br></div><div>Thanks for writing up your thoughts Zane - glad to know we're all noodling on this together.</div><div><br></div><div>Anne</div><div><br></div><div>[0] <a href="http://developer.openstack.org/api-ref.html">http://developer.openstack.org/api-ref.html</a></div><div>[1] <a href="http://en.wikipedia.org/wiki/Long_tail">http://en.wikipedia.org/wiki/Long_tail</a></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
cheers,<br>
Zane.<br>
<br>
<br>
______________________________<u></u>_________________<br>
OpenStack-dev mailing list<br>
<a href="mailto:OpenStack-dev@lists.openstack.org" target="_blank">OpenStack-dev@lists.openstack.<u></u>org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/<u></u>cgi-bin/mailman/listinfo/<u></u>openstack-dev</a><br>
</blockquote></div><br></div></div>