Jump to: navigation, search

Documentation/ReorganizeUserGuides

< Documentation
Revision as of 07:23, 26 August 2015 by Jaegerandi (talk | contribs) (Link checks and changes)

Reorganise the User Guide - Task List

Paired with the User Guide Specialty team page, this list of tasks to complete the project helps to keep track of changes to information architecture, consistency, and conventions in the guides.

Please add your name next to one of the tasks on the List of Tasks to prevent duplication of improvements detailed in the docs spec.

Link checks and changes

After conversion to .rst format, links to the Cloud Admin Guide (please check also End User Guide, Admin User Guide, and Security Guide links - a "/content" in the URL is always wrong for these) from across the docs and projects have changed. These all need to be updated. Below is a list tracking the OpenStack doc project, and the reviews that target the links within each doc project:

Document/section Name Patch URL Status
openstack / install guide Brian Moss https://review.openstack.org/#/c// Ongoing
openstack / glance Andreas Jaeger https://review.openstack.org/#/c/216003/ On review
openstack / user-guide Tamara Johnston https://review.openstack.org/#/c/216909 On review
openstack / user-guide-admin Tamara Johnston https://bugs.launchpad.net/openstack-manuals/+bug/1488703 Bug filed
openstack / networking-guide Tamara Johnston https://bugs.launchpad.net/openstack-manuals/+bug/1488713 Bug filed
stackforge / fuel-docs - - Open
openstack / cinder-specs Christian Berendt https://review.openstack.org/216116 On review
openstack / nova-specs - - Open
openstack / training -guides - - Open
openstack / neutron - - Open
openstack / ironic-specs - - Open
openstack / cinder - - Open
openstack / ceilometer Joseph Robinson - Open
openstack / api-site - - Open
openstack / ceilometer-specs - - Open
openstack / heat - - Open
openstack / governance - - Open
openstack / governance - - Open
stackforge / cookbook-openstack-network - - Open
openstack / designate-specs - - Open
openstack / docs-specs - - Open
stackforge / kolla - - Open
stackforge / networking-midonet - - Open
stackforge / driverlog - - Open
stackforge / kolla - - Open
openstack / neutron-specs - - Open
openstack / tripleo-image-elements - - Open
openstack-attic / object-api - - not needed (attic is read-only)
stackforge / fuel-plugin-lma-collector - - Open
openstack / openstackdocstheme Andreas Jaeger https://review.openstack.org/216121 Open
stackforge / fuel-plugin-neutron-fwaas - - Open
stackforge / os-ansible-deployment - - Open
stackforge / fuel-specs - - Open
openstack / swift - - Open
stackforge / compass-adapters - - Open
openstack / ha-guide Andreas Jaeger https://review.openstack.org/215998 Merged
openstack / operations-guide Andreas Jaeger https://review.openstack.org/215996 Merged
openstack / api-site Andreas Jaeger https://review.openstack.org/216001 Merged
openstack / cinder Andreas Jaeger https://review.openstack.org/#/c/216006/ Merged
openstack / security-doc Andreas Jaeger https://review.openstack.org/216004 Merged
openstack / admin-guide-cloud Andreas Jaeger https://review.openstack.org/#/c/216033/ Merged

Use hound.openstack.org to search for strings in all repos.

The List of Tasks

  • Remove duplication in table of contents
    • Several items repeat in the table of contents. Repairs to the RST files are needed. (DONE)
  • Separate User Guides in separate directories while keeping a common directory to simplify setup and writing: (DONE)
  • Develop the User Task Matrix
  • Rework the abstract for each guide to clearly identify audience and purpose.
    • Include new overview/descriptive information in the guide where such information is missing or needs updating.
  • Convert Cloud Administration Guide to RST
  • Move Hot Guide from End User Guide to Heat repo
  • Reduce duplication of content between the guides, pointing the Cloud Admin Guide to the Admin User Guide, and Admin User Guide to the End User Guide for readers to accomplish further tasks, which is a suitable step for the abstract rewrite
  • Remove any unnecessary or self-explanatory procedures from the dashboard chapter
  • Determine a good structure for how to present tasks - Dashboard, Command-line, or Config File edits
  • Update the images (.jpg etc) of the dashboard for the Admin and Projects tabs
  • Bring consistency to certain procedures within the guide. Some have tables, while some have variable lists:
    • Create Network (normal variable list)
    • Launch Instance (variable list in bold)
    • Manage stacks and Access & Security (tables)
    • Mange objects (bullets)
  • Spacing between steps in procedures are inconsistent. Example: "Procedure To Copy an Object From One Container to Another" and

"Procedure: To Create a Metadata-only object without a file" in the "Manage and Object" section of the User Guide. - Joseph Robinson

Cloud Admin Guide RST Conversion

  • One of the OpenStack Docs selected for Conversion after the Vancouver 2015 design summit is the Cloud Admin Guide. Converting the guide to RST is now a task and a priority of the User Guide Speciality team.
  • When conversion is complete, we can reorganize the content of the Cloud Admin Guide, Admin User Guide, and End User Guide.

Additional Information

temporary bug list

A list of bugs to be added to the blueprint whiteboard once it is ready: