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.
