Open Stack

 TL;DR Each day there was something for docs. The summaries are as follows:

Monday:Developer Support; Enterprise with an Upstream

Tuesday:Design Guide panel; training group; and Scaling Docs

Wednesday: Infra Guide for self-service infra and all-OpenStack style guide

Thursday: Operators Docs; API Ecosystem for applications

Friday: Docs deep dive including new design (Squee!)

-----------
Monday

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
https://github.com/rackerlabs/peril for code.

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
https://www.openstack.org/summit/openstack-paris-summit-2014/session-videos/presentation/writing-enterprise-docs-with-an-upstream-a-life-lesson-in-giving-back

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.

I also did a lot of working sessions with the API Working Group, double
session: https://etherpad.openstack.org/p/kilo-crossproject-api-wg

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
https://wiki.openstack.org/wiki/API_Working_Group/API_Current_States. 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.

Tuesday
I tweeted a bunch from the Design Guide Panel so that's a decent summary
starting with https://twitter.com/annegentle/status/529628636362854400

After this session I literally ran over to the Scaling Documentation across
projects session across the street.

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.

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.

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.

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.

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.

Thursday API Ecosystem Group session:
https://etherpad.openstack.org/p/kilo-summit-ops-app-eco

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.

Friday
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.

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.

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.

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.

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.

We went through the new designs for the landing page, a content page, and
the search page. https://etherpad.openstack.org/p/docstopicsparissummit

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:
https://docs.google.com/document/d/1GGKTKHDMc8A0jerdv-K3ql0udnxMr-j4DlhL2Cj6kcw/edit

The solutions defined in the designs here:
Main page - http://openstack-homepage.bitballoon.com/docs
Book Content view - http://openstack-homepage.bitballoon.com/docs/book
Search results - http://openstack-homepage.bitballoon.com/docs/search

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.

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.

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.

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.

Merci,
Anne
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20141109/25980ff6/attachment-0001.html>