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 as links 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. Let us know what you think of this approach by taking a look at the pending review. 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 how to custom brand the OpenStack Dashboard.
- Add link to helpful blog entries to a “BloggersTips” wiki page.
- Expand the install/deploy guide to include more distros so the “single distro” guides can standalone. This effort is still a work in progress.
- Hastexo has offered to write a separate high availability (HA) guide, so we won’t bring in their 12.04 “all in one” install guide after all, since the CSS OSS Starter Guide covers a similar scenario.
- Remove “articles” from RST docs. (Currently nova only, in further discussion with the Project Technical Leads, QA and CI team leads.)
- 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.
What we’ve discussed:
- Removing redundant docs. 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 who want to write compose WordPress “articles” and that would 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 knowledge 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. Now get started!
