Overhaul of the current OpenStack-Ansible Installation Guide

date:

2016-05-31 00:00

tags:

docs

Blueprint: Overhaul of the current OpenStack-Ansible Installation Guide

After the 2016 Austin summit, there was a discussion and a consensus surrounding the current state of the OpenStack-Ansible Installation Guide.

Note

A blueprint and spec were previously created with the intention of improving the documentation that pushed the summit discussion.

Currently, the OpenStack-Ansible install guide has minimal installation information, and a lot of configuration information. This specification proposes a more formalized plan to separate this information and streamline the installation guide to make it easier and quicker to install OpenStack.

Problem description

The OpenStack-Ansible Installation Guide contains information that does not necessarily pertain to that of an installation guide structure. It has accumulated a lot of configuration information and reference information that reduces the user’s focus and simplicity to install OpenStack.

The current installation guide also does not follow the openstack-manuals documentation conventions.

Proposed change

The main focus of the installation guide is reorganising and developing content so a deployer makes very few decisions and minimal configuration to deploy an OpenStack test environment and production environment.

The proposed changes are:

  • Clearly define reference architecture and develop use case configuration examples in an appendix.

  • Removal of the configuration information from the current installation guide and including it in the OpenStack-Ansible role documentation.

  • Migrate operations content temporarily to openstack-ansible-ops repo until an operations guide can be produced.

  • Restructure the guide to include basic deployment configuration.

  • Appendices that include configuration file examples, neutron plugins, cinder options and additional resources relevant to an OpenStack-Ansible installation.

  • Include links to role based documentation from the Installation Guide.

Alternatives

  • Leaving the installation guide as is, and migrating only the configuration information to the developer docs.

  • Consider revising the installation guide to meet criteria in project-specific installation guide and publish to docs.openstack.org

Playbook/Role impact

N/A

Upgrade impact

N/A

Security impact

N/A

Performance impact

N/A

End user impact

These changes will hopefully improve the end user experience, by providing a more structured and better flow of information to install OpenStack.

Deployer impact

N/A

Developer impact

Move existing content over to the roles first, then developers must submit any new documentation to the role repositories.

Dependencies

N/A

Implementation

Assignee(s)

Primary assignee:

Alexandra Settle (asettle)

Other contributors:

Darren Chan (darrenc), Jesse Pretorius (odyssey4me), Travis Truman (automagically), Major Hayden (mhayden)

Work items

  • Clarify and obtain consensus on the content structure

  • Gather information from SMEs as needed

  • Create a draft directory for installation guide changes

  • Create a work items list and allocate resources

  • Ensure documentation meets openstack-manuals writing conventions

  • Test draft documentation before publication

Testing

The testing will be conducted by the community once a draft is available. OpenStack-Ansible users will be asked to follow the new installation guide to install OpenStack and evaluate if the information provided is accurate, clear, and concise.

Documentation impact

This is a documentation change, N/A.

References