Jump to: navigation, search

Difference between revisions of "Documentation/ReorganizeUserGuides"

m (Link checks and changes)
m (Link checks and changes)
Line 37: Line 37:
 
| openstack / api-site || Emett Speer  || https://review.openstack.org/219944 || Merged
 
| openstack / api-site || Emett Speer  || https://review.openstack.org/219944 || Merged
 
|-
 
|-
| openstack / ceilometer-specs || || - || Open
+
| openstack / ceilometer-specs || Brian Moss || https://review.openstack.org/#/c/224432/ || On review
 
|-
 
|-
 
| openstack / heat || Brian Moss  || https://review.openstack.org/#/c/219071/ || Merged
 
| openstack / heat || Brian Moss  || https://review.openstack.org/#/c/219071/ || Merged

Revision as of 05:48, 17 September 2015

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/217524/ Merged
openstack / glance Andreas Jaeger https://review.openstack.org/#/c/216003/ Merged
openstack / user-guide Tamara Johnston https://review.openstack.org/#/c/216909 Merged
openstack / user-guide-admin Brian Moss https://review.openstack.org/#/c/224415/ On review
openstack / networking-guide Brian Moss https://review.openstack.org/#/c/224416/ On review
stackforge / fuel-docs Brian Moss https://review.openstack.org/#/c/219069/ On review
openstack / cinder-specs Christian Berendt https://review.openstack.org/216116 On review
openstack / nova-specs Christian Berendt https://review.openstack.org/#/c/216122/ Open
openstack / training -guides Brian Moss Waiting for creation of new repos On hold
openstack / ironic-specs - - Open
openstack / ceilometer Joseph Robinson - Open
openstack / api-site Emett Speer https://review.openstack.org/219944 Merged
openstack / ceilometer-specs Brian Moss https://review.openstack.org/#/c/224432/ On review
openstack / heat Brian Moss https://review.openstack.org/#/c/219071/ Merged
openstack / governance - - Open
stackforge / cookbook-openstack-network - - Open
openstack / designate-specs - - Open
openstack / docs-specs Emett Speer https://review.openstack.org/#/c/219936/ On review
stackforge / kolla - - Open
stackforge / networking-midonet - - Open
stackforge / driverlog - - Open
stackforge / kolla - - Open
openstack / neutron-specs Emett Speer https://review.openstack.org/219942 Merged
openstack / tripleo-image-elements Emett Speer https://review.openstack.org/219945 Open
openstack-attic / object-api - - not needed (attic is read-only)
stackforge / fuel-plugin-lma-collector Brian Moss https://review.openstack.org/#/c/219525/ Merged
openstack / openstackdocstheme Andreas Jaeger https://review.openstack.org/216121 Merged
stackforge / fuel-plugin-neutron-fwaas Brian Moss https://review.openstack.org/#/c/219527/ On review
stackforge / os-ansible-deployment Brian Moss https://review.openstack.org/#/c/219085/ Merged
stackforge / fuel-specs - - Open
openstack / swift Emett Speer https://review.openstack.org/219933 Merged
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
openstack / neutron Christian Berendt https://review.openstack.org/#/c/216125/ 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 (DONE)
  • Move Hot Guide from End User Guide to Heat repo (DONE)
  • 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 (WORKING ON) Darren Chan
  • Bring consistency to certain procedures within the guide. Some have tables, while some have variable lists: (WORKING ON) Joseph Robinson
    • 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 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. -

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: