Architecture Design Guide Improvements

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

Review, edit, and reorganize the Architecture Design Guide.

Problem description

The Architecture Design Guide has not been thoroughly reviewed since its creation. This has led to the following issues:

  • language and syntax not in accordance with our conventions
  • improvable information architecture
  • duplication of content

Proposed change

  • Reorganize guides to improve presentation of existing content
  • Clean up existing content where necessary and remove duplication
  • Identify information gaps and raise bugs where necessary

This work is a precursor to converting this guide from Docbook XML to RST in a future release.

Alternatives

  • Leave the guide as it is
  • raise bugs against each individual section that requires improvement

Implementation

Assignee(s)

Primary assignee:
Brian Moss (bmoss)
Other contributors:
Documentation Swarm attendees

Work Items

The bulk of this work is expected to be completed at the upcoming documentation swarm taking place in Brisbane AU on August 13-14. See References.

  • Rework the abstract to clearly identify the audience and purpose of the book
  • Reduce duplication in the guide as much as possible.
  • Edit for consistency and adherence to our conventions
  • Move sections as required to improve information architecture

Dependencies

None

Testing

Standard documentation review process.