Difference between revisions of "Documentation/IncubateIntegrate"

Revision as of 18:07, 26 August 2014

Incubating projects and documentation

You're applying for incubation, congrats! I know you've studied the Minimal Requirements for Incubation and Integrated Status https://github.com/openstack/governance/blob/master/reference/incubation-integration-requirements.rst. You may wonder what the "documentation" requirements are at each stage. Let's walk through them with examples.

The TC only expects to see contributor documentation during an incubation application. We figure you're looking to recruit more Python developers to help you accomplish your goals. OpenStack projects do some project documentation on the wiki for starters, such as during the application process.

You just got incubated, now what?

While you're incubating we like to see documentation in your repo in doc/source, built with Sphinx. You can start to use the oslosphinx theme, a common theme for OpenStack projects, at the point your project begins incubation. You must indicate that you're incubating by setting the oslosphinx configuration by ensuring your sphinx conf.py has incubating set to True for the theme:

   'html_theme_options = {'incubating': True}'

You can publish to docs.openstack.org/developer while incubating. Prior to incubation we suggest publishing to ReadTheDocs.org or your own domain and avoid using the OpenStack logo or trademark unless you have permission as outlined in the brand guidelines from http://www.openstack.org/brand/.

While you're incubating and gathering developer contributors, be sure to also find writer resources. Your developers can probably manage the contributor developer documentation but be thinking about how you'll write your REST API reference documentation, your install documentation, your configuration documentation, your operator and admin documentation, and end-user documentation for CLI and dashboard interaction. You'll need to prove you're able to support your users (ops, admins, and end-users) when graduating to integrated, through docs and answers on ask.openstack.org.

While you're integrating, I'd suggest that your doc/source directory become the landing place for your documentation. What you'll want to look forward to is writing in such a way that your pages can be used for these deliverables in the official OpenStack documentation, found at https://wiki.openstack.org/wiki/Documentation/ContentSpecs.

Always be aware that the OpenStack Documentation Program prioritizes the core projects above integrated, but we provide frameworks and reviews and try to help with orientation as much as possible. We're just not in a position to provide shared resources such as technical writers assigned to each project, for example. Rather, we expect the projects to assign a doc liaison who can interact with the documentation group through the openstack-docs mailing list and #openstack-doc IRC channel. The docs team holds weekly meetings and it's great to have doc liaisons attend the meetings that are in their time zone. The meeting schedule and agenda are found here: https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting.

Here's a worked example for the Barbican project, currently in an incubation stage:

• Contributor developer documentation is published to https://github.com/cloudkeep/barbican/wiki/Developer-Guide, but linked from http://docs.openstack.org/developer/barbican/, which is sourced from https://github.com/openstack/barbican/blob/master/doc/source/index.rst

• REST API documentation is in the openstack/barbican repo, a Developer Guide has JSON samples and WADL references. The WADL can eventually be used for the API reference at developer.openstack.org/api-ref.html.

• They've got an Install Guide started with no content in DocBook -- it doesn't have to be in DocBook at this stage, you could put it in the Sphinx docs.

• They've got release notes started with no content, again this could be in the Sphinx docs.

• Due to the project's topic being related to security and identity, be thinking about the Security Guide specifically and how to fit in there.

• For config information, use Oslo common to help with automation of the configuration reference. It builds docbook tables currently.

• For CLI information, after incubation we can automatically bring in the --help information so be sure it's helpful.

You're applying for graduation to integrated and wondering, what docs are needed? How are they written? (And what's passive voice?) When do they land on docs.openstack.org? Let's keep going.

Integrating projects and documentation

A project can integrate as quickly as a one-release-cycle timing such as icehouse to juno. This means there's about six months to ensure the project is supporting deployers and end users as expected with docs and responses to mailing list posts and ask.openstack.org. As stated, since the Docs Program does not offer extra resources to integrated projects, each team needs to find the resources they can to write their docs.

Let's walk through an example of a project that's working on integrating documentation after graduation. The Telemetry module written by the ceilometer project does these things:

• Automate REST API documentation programmatically then patches and maintains a WADL into the api-site repo while also writing to http://docs.openstack.org/developer/ceilometer/webapi/v2.html

• Provides a reference of all the measurements they collect for each project

• Describes how to install

• Describes Configuration options including those that matter for cross-project integration

• Provides release notes

• Adds Telemetry administration topics in a chapter addition to the Cloud Admin Guide

How about Sahara? It's integrated in Juno. What are they doing towards the documentation goals?

• We merged in their CLI Reference patch to openstack-manuals. (Even though they're not official integrated until the Juno release and that's a continuously integrated deliverable).

• They're doing their Installation, Configuration, and Upgrade Guides on their developer documentation site at http://docs.openstack.org/developer/sahara/. I envision it wouldn't be difficult for them to propose a patch for the Install Guides for example as an optional chapter like the Databases one.

• They also have a UI Configuration guide to make sure the OpenStack dashboard (horizon) can show sahara Hadoop clusters. Nice!)

• Like the Database project trove, they have you register an image, so they may want to update the Virtual Machine Image Guide like the trove team has.

• They've got a full-featured Developer Guide with programming tutorials for contributors.

• They've documented their REST API at http://docs.openstack.org/developer/sahara/restapi/rest_api_v1.0.html but no WADL to date, so they won't show up on developer.openstack.org/api-ref.html. Timing-wise, I wouldn't expect them to show up in official OpenStack docs until Juno is released this fall though, since it's not packaged up yet.

In summary, the guidance for incubating and integrating for documentation is brief, but the actual documentation work is expansive. The publishing timing should co-incide with the release itself. The docs team likes to work with project liaisons and provides some tooling assistance, and also relies heavily on Oslo. Documentation is never done, but we use the same processes as the rest of the OpenStack projects including bug tracking, patches and reviews in Gerrit, and as much automation as we can.