Reorganize User Guides for Liberty¶
Update the information architecture of the Cloud Administrator Guide, Admin User Guide, and End User Guide to separate user, administrator, and operator content, and ensure that the existing content is accurate and relevant.
The current user guides have become disorganized over time, this update tidies them up.
- Clarify the audience of each guide
- Identify different types of content in the guides
- Reorganize guides to better present existing content
- Clean up existing content where necessary
- Identify information gaps and raise bugs where necessary
- Be sure that terms are well-defined here (or link to other docs for definitions)
- Leave the guides as they are
- Combine the Cloud Admin Guide and the Admin User Guide
- Combine the Admin User Guide and the End User Guide
- Primary assignee:
- Lana Brindley (loquacity)
- Other contributors:
- The User Guides specialty team Anyone with information architecture experience
- Develop a user/task matrix and define a limited set of personae to consume the user guide content.
- Rework the abstract for each guide to clearly identify the audience and purpose of each book
- Remove the unnecessary/self explanatory procedures from the dashboard chapter, for example, ‘Delete an image’ or ‘Manage an instance’ and so on.
- Determine a good structure for how to present tasks, using the dashboard or CLI, and editing config files.
- Reduce duplication between the guides as much as possible. Point the Cloud Admin Guide to the Admin User Guide, and the Admin User Guide to the End User Guide for readers to accomplish further tasks. This information may be suited to the Abstracts.
- Update dashboard images for Admin and Project tabs.
- Verify if the procedures are applicable by testing against the Liberty puddle.
- Consistency with procedures: some have tables, some use variable
list, for example:
- Create Network (normal variable list)
- Launch Instance (variable list in bold)
- Manage stacks and Access & Security (tables)
- Manage objects (bullets)
- Spacing between steps in procedures is inconsistent, for example, check “Procedure To copy an object from one container to another” and “Procedure: To create a metadata-only object without a file” in the “Manage an object” section of User guide.
- Some of the topics are repeated in TOC, for example: In the User guide, Log in to the dashboard in the OpenStack Dashboard chapter and from Overview to Manage volumes in the OpenStack command-line clients chapter. [http://docs.openstack.org/user-guide] Similarly, some of the sections are repeated in the admin user guide. [http://docs.openstack.org/user-guide-admin]