[openstack-dev] What's Up Doc? Apr 4 2014

Anne Gentle anne.gentle at rackspace.com
Fri Apr 4 16:56:36 UTC 2014


Please take this survey to understand the obstacles to doc contributions.
We are very interested in increasing the doc contributions and making our
doc processes work well for OpenStack as it scales. I believe we can take
actions based on the questions here, please send the link to OpenStack
contributors as far as you can!

https://docs.google.com/forms/d/136-BssH-OxjVo8vNoOD-gW4x8fDFpvixbgCfeV1w_do/viewform

1. In review and merged this past week:
We've reviewed and merged nearly 60 patches this week. I would like to see
this pace increase however as we need to keep working on the backlog of
over 350 doc bugs in openstack-manuals alone. We are definitely patching
doc bugs with the items that landed recently, let's keep it up!

2. High priority doc work:

Install Guide, install guide, install guide. We are testing and updating
and Matt Kassawara has been leading the way to get Networking scenarios
tested and documented. Matt's asking an important question on the -docs
list: Shall the docs support both OVS and ML2 in the installation guide
(with removal of OVS in Juno instead of Icehouse?) Please join in at
http://lists.openstack.org/pipermail/openstack-docs/2014-April/004204.html

Doc bugs generated from DocImpact are also a high priority. Please refer to
https://launchpad.net/openstack-manuals/+milestone/icehouse. As Tom noted,
we need to fix six bugs a day to make our docs bug list goals. There are
still 118 bugs awaiting your input. Even if you can only triage or comment
on a bug, every effort helps.

If you prefer to work on bugs against API docs, refer to
https://launchpad.net/openstack-api-site/+milestone/icehouse.

Release notes are a high priority. It's release time, can you tell?

3. Doc work going on that I know of:

ML2 driver documentation for compute, controller, and network nodes in
Install Guides
ISO Image documentation
Trove install documentation
Scheduler filter documentation

4. New incoming doc requests:

Lots of users want Trove documentation.

5. Doc tools updates:

We will freeze on 0.10.0 of openstack-doc-tools and 1.15.0 of
clouddocs-maven-plugin for the Icehouse doc builds.

6. Other doc news:

I've proposed a cross-project session for the Summit at
http://summit.openstack.org/cfp/details/204. I'd love to hear your thoughts
on these ideas -- at the session or on the list.
We have different docs for different audiences:
cross-project docs for deploy/install/config: openstack-manuals
API docs references, standards: api-site and others

These are written with the git/gerrit method. I want to talk about standing
up a new docs site that serves these types of people with these
requirements:

Experience:
Solution must be completely open source
Content must be available online
Content must be indexable by search engines
Content must be searchable
Content should be easily cross-linked by topic and type (priority:low)
Enable comments, ratings, and analytics (or ask.openstack.org integration)
(priority:low)

Distribution:
Readers must get versions of technical content specific to version of
product
Modular authoring of content
Graphic and text content should be stored as files, not in a database
Consumers must get technical content in PDF, html, video, audio
Workflow for review and approval prior to publishing content

Authoring:
Content must be re-usable across authors and personas (Single source)
Must support many content authors with multiple authoring tools
Existing content must migrate smoothly
All content versions need to be comparable (diff) across versions
Content must be organizationally segregated based on user personas
Draft content must be reviewable in HTML
Link maintenance - Links must update with little manual maintenance to
avoid broken links and link validation
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20140404/0c71239d/attachment.html>


More information about the OpenStack-dev mailing list