<div dir="ltr">







TL;DR Each day there was something for docs. The summaries are as follows: <br><br>Monday:Developer Support; Enterprise with an Upstream<br><br>Tuesday:Design Guide panel; training group; and Scaling Docs <br><br>Wednesday: Infra Guide for self-service infra and all-OpenStack style guide<br><br>Thursday: Operators Docs; API Ecosystem for applications<br><br>Friday: Docs deep dive including new design (Squee!)<br><br>-----------<br>Monday<br><br>Right after the keynotes I had my developer support talk. I did a deep dive into the data I see while supporting developers using OpenStack APIs — it’s not just docs that support them, it’s Q&A sites, Github Issues, and SDK work. Our tool, peril, helps us discover when a developer needs help. See <a href="https://github.com/rackerlabs/peril">https://github.com/rackerlabs/peril</a> for code.<br><br>Monday afternoon Lana Brindley, Rackspace tech pubs manager in Australia and I gave a talk about what it’s like to contribute to an upstream open source project when you have enterprise concerns. We refined and defined quite a bit more since we gave this talk at an internal Rackspace Docs Summit and that further iteration went really well. See the video at <a href="https://www.openstack.org/summit/openstack-paris-summit-2014/session-videos/presentation/writing-enterprise-docs-with-an-upstream-a-life-lesson-in-giving-back">https://www.openstack.org/summit/openstack-paris-summit-2014/session-videos/presentation/writing-enterprise-docs-with-an-upstream-a-life-lesson-in-giving-back</a><br><br>After this session, I got to see a spreadsheet for the API documentation they needed internally. He wanted to know how to add it to the API site, so I showed him our source files. Perhaps we’ll see some patches, he was also at the operator’s “hacking documentation” session paying careful attention while we demonstrated our processes.<br><br>I also did a lot of working sessions with the API Working Group, double session: <a href="https://etherpad.openstack.org/p/kilo-crossproject-api-wg">https://etherpad.openstack.org/p/kilo-crossproject-api-wg</a><br><br>We had three sessions total this week, and Everett Toews does a great job in facilitating these discussions and keeping us on track. I want to point out a page for our team to take a look at as a result of our discussions. I’ve started a working page with an API implementation matrix at <a href="https://wiki.openstack.org/wiki/API_Working_Group/API_Current_States">https://wiki.openstack.org/wiki/API_Working_Group/API_Current_States</a>. The goal is to show the current states of the APIs and where they are already inconsistent. We’ll also start meeting weekly with alternating time zones that work well for North America as well as the rest of the world.<br><br>Tuesday<br>I tweeted a bunch from the Design Guide Panel so that's a decent summary starting with <a href="https://twitter.com/annegentle/status/529628636362854400">https://twitter.com/annegentle/status/529628636362854400</a><br><br>After this session I literally ran over to the Scaling Documentation across projects session across the street.<br><br>Scaling Documentation cross project session had about 30 people in the session, many from last time where we had 2 sessions about developers, projects, writers, and docs. Neat outcomes. I think Andreas now understands “every page is page one” — so that now we can move to our new web design (more on that below). I think Andreas also has a great idea about how to make index.rst files that will cross multiple projects. We have big ideas about how to make Sphinx do our bidding with tagging pages and index.rst files built on directories from each repo. Should be interesting! Andreas is going to start a playground/sandbox for us to experiment with and to train teams with. Going to RST is going to help immensely of course, but we also need our rock-solid style guide, review turnaround times, and design.<br><br>In this session, Zane Bitter, a Heat developer said, “You won’t write documentation, you’ll write documentation about how to write documentation.” Not sure that’s completely true but when you go from 2 projects to 17 in two years it’s completely feasible we’ll be at 50 projects in another 2 years, so the scaling has begun in earnest. At the tail end of this project we talked about WADL to Swagger conversion with Max in the room as well. <br><br>The Training team met twice this week and I think they have a new, more focused direction, still working with the docs team but displaying their further refinements closer to the actual training marketplace. I think they understand now they need to focus more narrowly on a particular audience rather than trying to cover everything. They’ve also got the upstream training materials in their repo now which I find really exciting. I had to miss their second meeting on Thursday so please post any summaries here to the list.<br><br>Wednesday I reminisced with others Four-Years-In Stackers in a panel. Andreas represented docs at the infrastructure session and will help them review content using our style guide, adding to it as needed.<br><br>Thursday, at the Operators sessions, we held an hour session about documentation hacking with operators with about 25 people, buried in the Hyatt. We walked through how to log bugs, how to triage bugs, how to do reviews, and how to patch documentation. I think a lot of people are interested from the ops side. Harry Sutton, who recently posted about troubleshooting content and I talked about them giving some troubleshooting content upstream so look for those to review. We have some storage (volumes) troubleshooting content and networking troubleshooting content so hopefully we can keep adding to that. Feedback is that we don’t need a separate upgrade guide, that the ops guide is just fine, but that the architecture guide needs more meat on the bones with real configurations. <br><br>Thursday API Ecosystem Group session: <a href="https://etherpad.openstack.org/p/kilo-summit-ops-app-eco">https://etherpad.openstack.org/p/kilo-summit-ops-app-eco</a><br><br>This group wants to run a content sprint with a group of people who could write a sample app deployed on an OpenStack cloud, any OpenStack cloud, with a tutorial to go along with it. Tom Fifield agreed to be a facilitator, and Everett and I will likely be looking for candidates to go to this sprint who can bravely work on the first ever “Pet store” for OpenStack clouds. Very interesting suggestion to come out of that session.<br><br>Friday<br>On the last day we had a great break-through docs session. I know there was a lot of pent-up need for discussion amongst the writers who don’t need a “101” session on docs. We talked about bugs, information architecture, and resourcing. We didn’t even get to the last topic of how to apply consistency to the doc set, but we all agree consistency is a priority. <br><br>Our bug backlog is the largest of any OpenStack project at over 600 bugs for openstack-manuals and openstack-api-site. That is because of the exponential growth of the collection of OpenStack projects. It’s also because we struggle between writing common docs and writing project docs. Plus the DocImpact queue just gets longer and longer without assigned writers as devs continue to throw bugs over the wall without circling back to ensure they’re assigned. The long bug backlog is also due to the driver documentation requiring a lot of additions to the official doc set. <br><br>Our plan going forward for driver documentation will be communicated broadly in more detail. The new model is to document open source drivers as a priority in the official docs, with the default as the most important. This narrows down the driver docs considerably. Then we will maintain a list of drivers and point to vendor documentation for the rest. For Block Storage, cinder, this means only LVM will be documented in the official docs. For Compute, nova, only KVM will be documented with Xen open source as a possible secondary if we can find someone who knows enough to update and maintain what we have. For Networking, neutron, only document the OpenVSwitch and Linux Bridge implementations of the ML2 driver. To summarize, our new guidelines are to:  1) link to external docs only, 2) list them only when the project itself has the driver in their "third party" tree, 3) document the open source default driver first. All the other drivers are link-only. Andreas Jaeger will write up a spec for all to review.<br><br>We discussed DocImpact and APIImpact. Lana is going to investigate a review system where the original dev takes more responsibility for reviews (and assignment) of any patches with DocImpact. I’m going to look into making bugs in openstack-api-site automatically when APIImpact is set on a patch since nearly always the docs will be affected.<br><br>We’ll also start to do a monthly bug triage day, different from a bug fixing day, where we clear out the bug queue together and triage them to be ready for work. I’ll describe it and set it up for this month, November.<br><br>We went through the new designs for the landing page, a content page, and the search page. <a href="https://etherpad.openstack.org/p/docstopicsparissummit">https://etherpad.openstack.org/p/docstopicsparissummit</a><br><br>This morning I sent a list of input to the designer after we reviewed the design. The designs are available to see. For some background, the various design problems we currently face are defined in the design brief at: <br><a href="https://docs.google.com/document/d/1GGKTKHDMc8A0jerdv-K3ql0udnxMr-j4DlhL2Cj6kcw/edit">https://docs.google.com/document/d/1GGKTKHDMc8A0jerdv-K3ql0udnxMr-j4DlhL2Cj6kcw/edit</a><br><br>The solutions defined in the designs here:<br>Main page - <a href="http://openstack-homepage.bitballoon.com/docs">http://openstack-homepage.bitballoon.com/docs</a><br>Book Content view - <a href="http://openstack-homepage.bitballoon.com/docs/book">http://openstack-homepage.bitballoon.com/docs/book</a><br>Search results - <a href="http://openstack-homepage.bitballoon.com/docs/search">http://openstack-homepage.bitballoon.com/docs/search</a><br><br>Gerrit has a web-based editor for text-based files coming in the next release. We want to incorporate it into the docs workflow so that it’s easier to do small changes. <br><br>I also plan to get regular video-based meetings going so that we can continue our discussions with everyone who was there and wasn’t there. <br><br>I never did get to sit down with you, Thomas Goirand! Sorry about that. I also worry that I was so busy that I didn’t meet with others who needed to, so feel free to reach out to me any time for a chat. <br><br>Seeing this write up, I know my finely split attention means that not everything gets the attention it deserves. I’m definitely looking at all the leadership we have in our community and appreciating how well this week worked. Thank you all for patching and reviewing this past week and for representing documentation so well in our community.<br><br>Merci,<br>Anne</div>