|
|
| (363 intermediate revisions by 45 users not shown) |
| Line 1: |
Line 1: |
| − | __NOTOC__
| + | Read the new content in the [http://docs.openstack.org/contributor-guide/index.html Documentation Contributor Guide]. |
| − | = How To Work on [[OpenStack]] Documentation =
| + | {{OpenStack_Documentation_Navbar}} |
| | | | |
| − | At the core of OpenStack is the community and collaboration that we do - the same rules for the code apply to documentation too. Ideally any code contribution that is merged into the base has documentation to go with it. Anne Gentle is the coordinator for all documentation efforts, both community-based and "official" docs. This page describes the methods we use to create the basis for world-class documentation for OpenStack developers and users.
| |
| | | | |
| − | == Tools ==
| + | ---- |
| − | | + | [[Category:Documentation]] |
| − | Currently, we use both a wiki and RST files ([http://docutils.sourceforge.net/docs/user/rst/quickref.html ReStructured Text], it has a similar text-based markup as wikitext) to create web documentation. We are also building docs.openstack.org, which contains docbook as its source.
| |
| − | | |
| − | The wiki is easy-peasy, you just create an account on wiki.openstack.org, create a new page, and start editing.
| |
| − | | |
| − | Editing RST or docbook has a few more steps. If you're on Mac or Linux (ubuntu for example), you create a Launchpad account, install Bazaar (see http://wiki.openstack.org/LifeWithBzrAndLaunchpad) and get the code so you can work on .rst files in the doc/source/ directory in any project, nova, swift, or glance. To work on the docbook source file, a working project exists in Launchpad in the openstack-devel project since docbook documentation encompasses all three OpenStack projects.
| |
| − | | |
| − | The RST is built using Sphinx so that it gets displayed on [http://nova.openstack.org nova.openstack.org], [http://swift.openstack.org swift.openstack.org], and [http://glance.openstack.org glance.openstack.org].
| |
| − | | |
| − | A super light-weight drafting option, easy as a click-through, is to write with other collaborators on an Etherpad at http://etherpad.openstack.org/. We can invite others as we go, and choose to write it as wikitext, RST, or docbook.
| |
| − | | |
| − | == Audiences and Targets ==
| |
| − | | |
| − | OpenStack has three main projects - Compute (nova), Object Storage (swift), and now the Imaging Service (glance). While the goals you'd achieve using each project vary, the three projects can also be used together. Those three projects have two basic audiences - developers and sysadmins (think operations or even dev-ops). The RST-based documentation, because it automatically generates doc from docstrings in the code, is much more for a developer audience. The sysadmin audience is underserved in documentation deliverables currently, to put it plainly.
| |
| − | | |
| − | == Workflow ==
| |
| − | | |
| − | The workflow for documentation matches the workflow for code - you download a branch, work on it locally, then commit the changes and propose a merge. Your changes are merged into the main, published doc base, and the doc is built to its varying outputs.
| |
| − | | |
| − | == Translation ==
| |
| − | | |
| − | Translation efforts should occur either in the Launchpad Translations area (for strings in the code, error messages and the like) or on the wiki, which has translations enabled.
| |
