OpenStack Documentation Contributor Guide

updated: 2018-12-06 13:55

OpenStack Documentation Contributor Guide

https://blueprints.launchpad.net/openstack-manuals/+spec/docs-contributor-guide

Problem description

Based on the docs contributors experience and feedback, the information for the documentation contributors located on wiki sometimes contains outdated info and can be improved by restructuring and supplementing.

As we are treating our documentation as the code and willing others to do so, we need to relocate all the conventions, how to instructions and any docs contributor-related things to the place that fits as a single-entry, full, and neatly organized guide that answers questions that arise in the docs creation workflow.

The wiki is definitely not much convenient, it has narrowed functionality and lacks a number of features that have become essential part of any internet user nowadays, such as search, proper navigation, and some others.

Moving things around will noways influence its openness to the community or make the conventions less flexible. This will only unify and simplify the process.

Proposed change

We propose the creation of the Documentation Contributors Guide targeted at the contributors to the OpenStack documentation that will cover:

Documentation Contributors Guide: RST

Here is the table that lists the existing wiki content and outlines how it should be reworked from the contributor perspective:

Wiki page User story
HowTo As a docs contributor, I would like to know in details: what tools are required; how to edit, check builds and commit the changes; how to amend a review-in-progress, cherry-pick and make changes to a stable branch; how to work with launchpad bugs and review patches.
HowTo/FirstTimers As a docs contributor, I would like to have a quickstart guide with a suite of basic instructions on how to commit the change, respond to requests and troubleshoot.
Documentation/Builds and Documentation/ContentSpecs As a docs contributor, I would like to clearly understand what content goes where and where to get the sources (+ why the spec is required and how to create it)
Documentation/Conventions As a docs contributor, I would like to be aware of all the writing style guidelines that should be followed by the contributors to the OpenStack documentation.
Documentation/Markup_Conventions As a docs contributor, I would like to be aware of all the XML/RST markup guidelines that should be followed by the contributors to the OpenStack documentation.
Documentation/JSON_Conventions As a docs contributor, I would like to be aware of all the JSON guidelines that should be followed by the contributors to the OpenStack documentation.
Documentation/Structure As a docs contributor, I would like to be aware of how to name and arrange files and directories in books.

Note

HowTo and HowTo/FirstTimers are also covered by http://docs.openstack.org/infra/manual/developers.html. We should not duplicate but reference to it there.

Implementation

Work Items

  1. Create a separate wiki page to keep all the related details on the project.
  2. Work out the detailed and well-structured table of contents (on wiki).
  3. Create, and adjust a separate directory in openstack-manuals for the guide.
  4. Revise, move, and delete the existing (wiki) content.
  5. Create new content, which is required from the contributor perspective, for example, Screenshots and topologies guidelines.
  6. Make sure not to duplicate the content from http://docs.openstack.org/infra/manual/developers.html, but reference to it if it is required.
  7. Add the link to the docs contribution workflow to the Infra Manual.

Assignee(s)

Primary assignee:
Olga Gusarenko, ogusarenko

Other contributors:

Testing

Feedback from the docs contributors

References

  • Add the link to the project wiki page.
updated: 2018-12-06 13:55
Creative Commons Attribution 3.0 License

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.

questions?

docs-specs