openstack team mailing list archive

[Anne Gentle <anne@xxxxxxxxxxxxx>]

Hi all -
I wanted to send a note out to discuss the growth of all the starter docs
and "articles" on a particular topic. Thanks all who are sending these to
the mailing list or tweeting 'em. We are listening.

The doc team has been discussing ways to ensure we help people find what
they seek while still getting high-quality content into the "official"
documentation. Here are some ideas. I'd like to get input from our wider
community as well.

What we're doing:

 - Add a "Where do I start?" section to the docs landing page. [1] Let us
know what you think of this approach. We discussed quite a bit a more
friendly approach to the docs site but I haven't identified a web dev and
designer to do the re-do, contact me if you're interested.
 - Reach out to writers and where licensing allows and something "official"
is not already documented, bring the content into the official docs. We've
done this a few times now, an example is [2].
 - Add link to blog entry to wiki page. [3]
 - Expand the install/deploy guide to include more distros so the "single
distro" guides can standalone. [4]
 - Hastexo has offered to write a separate HA guide, so we won't bring in
their 12.04 "all in one" install guide after all, since the CSS OSS guide
covers a similar scenario.
 - Remove "articles" from RST docs. (Currently nova only, let's discuss,
PTLs, look for a separate email and read more below.)
 - Add blog URLs to the Google Custom Search Engine at
http://docs.openstack.org. I took this as an action item from our last doc
team meeting. [5]

What we've discussed:

 - At the Design Summit, members of the nova core team asked for removal of
"article" style RST documents from the nova source repo, creating a more
doc-string based nova.openstack.org. Members of the swift core team, when
asked, did not want to go to this architecture. I haven't specifically
asked all the PTLs on this particular item. So there's still a potential
problem here of consistency, where to write what, and having all the
project.openstack.org sites that aren't really tied together. I don't have
a good solution to suggest just yet but know we're thinking about this
particular problem. One idea was to have devs want to write WordPress
"articles" and aggregate together, but we haven't found an ideal
implementation (design is fine, working code, not so much).
 - Setting up a separate WordPress blog for documentation only. Apparently
the aggregation tools just don't give us all the requirements for version
labels, bringing in one blog entry at a time (RSS feeds are needed), and so
on.
- Setting up a "support knowlege base" article site such as
http://support.mozilla.org. We discussed this at the last doc team meeting.
It seems to solve a lot of problems we have, but my current thinking (which
of course can change) is that a support KB is for troubleshooting articles,
while the "official" docs should create a happy path. These are two
different scenarios, and I'm pretty sure the docs team cannot take on the
support scenario with our current resources. A support knowledge base with
translation built-in will go a long way in supporting our growing base, so
this is important to me, but not in the Folsom plans currently.

I'll follow up with each PTL for the docstring discussion, and welcome all
input. Thanks for reading this far, and thanks for the docs.

Anne


1. https://review.openstack.org/#/c/7372/
2. https://review.openstack.org/#/c/7366/
3. http://wiki.openstack.org/BloggersTips
4. https://review.openstack.org/#/c/7431/
5.
http://eavesdrop.openstack.org/meetings/openstack-meeting/2012/openstack-meeting.2012-05-14-19.59.html