Jump to: navigation, search

Documentation/ReorganizeUserGuides

< Documentation
Revision as of 05:16, 22 March 2016 by Asettle (talk | contribs) (→‎Up to Date Tasks)

Reorganise the User Guide - Task List

User Guide Specialty team page

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.

Up to Date Tasks

  • Identity Management (Joseph Robinson DONE)
    • Start the identity Service: Move this content into another section to reduce the number of files in the repository.
    • External authentication with Identity: Another smaller section in the identity service that can merge.
  • Dashboard
    • Merge Dashboard content from the Admin User Guide to the Dashboard chapter to create a new Dashboard section. Two halves: Part 1 (Joseph Robinson DONE) & part 2 (Gudrun Wolfgram DONE)
    • Check Liberty Dashboard updates and changes. (DONE - Kato Tomoyuki)
  • Command Line
    • Create a cli-index.rst file in the Cloud Admin Guide, and transfer the admin user guide items into the new location. (G. Wolfgram). Two halves. Part 1 & Part 2.
  • Compute (Alexandra Settle)
    • AMPQ: introductory colons to introduce a list. Capitalize abbreviations in brackets - change (ampq) to (AMPQ).
    • Hypervisors: Include a section on how-to use a hypervisor.
    • Tenants, users, roles: remove passive voice. Link to the "How Can I Use The Cloud?" section of the End User Guide - Create and manage roles - reorganize this **content to align with the Cloud Admin Guide content.
  • EC2 compatibility (Gudrun Wolfgram)
    • Remove passive voice.
    • Compare this section with the liberty installation guide.
  • Building Blocks
    • Introduction: Clarify what base operating system is referred to here. Check content for accuracy.
    • The nova image-list command. Link together the content on the nova command line client with the End User Guide here.
  • Images and Instances (Joseph Robinson DONE)
    • Align the introduction with the End User Guide.
    • "This diagram shows the system state prior to launching an instance" Describe the parts of the diagram. The paragraph is not clear. Extend the modifications to the other diagrams.
  • Networking with nova-network
    • Improving troubleshooting sections, as identified by recent research into user nova-network to neutron adoption and migration.
    • The Cloud Admin Guide references floating IP addresses, which users can change. The User Guide section on Networking will need reorganization to line up with this content. **Information on how to assign IP addresses to VM's also needs testing.
    • VLAN Network Manager: Check paragraph indentation.
    • nova network-create vmnet: Address table consistency across guides.
    • Configure Compute to use IPv6 addresses: Address table consistency across guides.
  • Metadata
    • Liberty to Mitaka-metadata services now include 'project_id' according to release notes.
    • Metadata needs an SME check for currency. (Andrew Bogott, John Garbutt, Matthiew Gagne)
    • Description of metadata config options table: Address table consistency across guides.
  • Flavors
    • Flavors define these elements table: Address tables consistency across guides. (Bold headings with sentences here).
    • Are the tables in the Admin User Guide on setting flavors effective?
    • Show Host Usage Statistics: Host usage statistics description, and change to bold headings.
  • Secure with Rootwrap
    • Configuration option [Default]: SME to check, and change to better format. Might need a code snippet
    • Migrate Instances: These tables were code snippets. Can they be replaced with images or appropriate code snippets?
    • VNC configurations options: Include a descriptions of VNC configuration options
    • Frequently Asked Questions: An FAQ in the guide clashes with the other information.
    • Information Architecture checkup needed here to rework this information.
    • Security Hardening: Improve the OpenStack with Trusted Compute Pools Second diagram. a new diagram needs headings, and consistency with the other diagrams.
    • Recover Cloud After disaster: Test or have SME check on this procedure.
  • Object Storage (DONE - Alexandra Settle - https://review.openstack.org/#/c/295622/)
    • User Guide: The Create and manage object containers section needs content from the introduction to the Object Storage section of the Cloud Admin. "...Object Storage (code-named swift is open source software for creating redundant, scalable data storage using clusters..."
    • Object Storage Characteristics - Does not mention containers, but the User Guide mentions this term. Edit for Consistency.
    • Components: Edit passive voice usage, and adjust the opening sentence introducing the components.
    • Rings: Underneath the Ring diagram, edit these sentences for a comma splice.
    • Zones: Mentions the high availability plus other components already mentioned in the Components section. So, Components description is not needed. Edit for repetition.
    • Partitions: Edit for punctuation - Comma Splice
    • Change the Cluster Architecture and Ring Builder Sections within the Block storage chapter.
    • Account Reaper: "In the background, the account reaper removes data from deleted accounts..." Edit the syntax here.
    • Object Storage Monitoring - Excerpt from a blog. Keep or remove? This section also needs a syntax review.
  • Block Storage
    • Block Storage: persistent storage needs to be mentioned earlier and more clearly in this introduction.
    • Migrate volumes: These commands could appear in the End User Guide
    • Block Storage command line list: "cinder-manager host lists", "cinder get-pools" Adapt for the Admin User Guide.
    • Back up and Restore volumes: Is this procedure a cloud admin procedure, or can the basic information be adapted to the User Guide? Requires role clarification.
    • Supported Operations in filter and goodness functions: Remove passive voice in the Caution note.
    • Rate-limit volume copy Bandwidth: Reorganize the guide such that this content appears closer to the information on moving and migrating block storage volumes ("volume_copy_bps_limit").
    • Image volume cache: Remove passive voice.
    • Multipath call failed exit: This Troubleshooting section recruits a Problem and Solution heading architecture useful for the other Troubleshooting sections of the Cloud Admin Guide. (Joseph Robinson)
  • Shared File System (Joseph Robinson DONE)
    • Share basic operations: " General concepts " edit or clarify this phrase.
    • Manage and unmanage share: Edit missing words in some sentences
    • Resize a share: Also missing words here.
    • Quotas and Limits: Edit verb subject agreement.
    • Consistency group: Edit verb subject agreements ("admin to admins").
    • Scheduling: Edit for article and definite articles.
    • Networking - Edit for missing words.
    • Share networks - Edit verb subject agreements
  • Networking
    • Plug-in configurations section: Document the most common ml2 plug-in configurations.
    • Reference network option plugins for ml2 http://docs.openstack.org/liberty/config-reference/ content/networking-options-plugins-ml2.html. See https://bugs.launchpad.net/openstack-manuals/+bug/1411624
    • Use Networking section: Networking Tables need consistency with the other Cloud Admin Guide tables.
    • Networking Architecture: This section's description of architecture would be better placed following the introduction.
    • Configuring Identity for Networking: A note about not using Nova-network with compute appears here, but needs to appear earlier - the introduction - as a warning for cloud administrators.
  • Database

No recommended changes currently.

  • Baremetal

No recommended changes currently.

  • Orchestration

No recommended changes currently.

  • Telemetry
    • Data Retrieval: The code snippet tables need to fit the page.
    • Measurements: Confirm that no other measurement items are added from the Liberty release. https://github.com/openstack/ceilometer/commit/43a50f9be884c731afc41a07442e2a8ddee6fc77 - CPU util checks added, and Magnum checks ("magnum sends the following: name: container.bay.memory_util, type: gauge, unit: %, resource_id: bay id, source: notification, description: memory utilisation of swarm bay"
  • Orchestration (Joseph Robinson)
    • Orchestration Authorization Model: This section requires an edit for grammar.
    • Stack domain users: Grammar Edits also required for this section.
    • Cross-origin resource sharing: The sub-section "enabling CORS with configuration" needs an edit to change into a procedure rather than a list of items.
  • Cross-project features

No recommended changes currently

File Tracking Table

Cloud Admin Chapter Admin Guide File Moved ? (Yes/No) Content added to a file, or added to a Toctree ? (Toctree/File)
Dashboard dashboard.rst Yes
admin-guide-cloud/source/dashboard.rst dashboard_admin_manage_stacks.rst Yes Toctree
admin-guide-cloud/source/dashboard.rst dashboard_manage_flavors.rst Yes Toctree
admin-guide-cloud/source/dashboard.rst dashboard_manage_host_aggregates.rst Yes Toctree
admin-guide-cloud/source/dashboard.rst dashboard_manage_images.rst Yes Toctree
admin-guide-cloud/source/dashboard.rst dashboard_manage_instances.rst Yes TocTree
dashboard_manage_resources.rst Yes TocTree
dashboard_manage_services.rst Yes TocTree
admin-guide-cloud/source/dashboard.rst shared_file_systems_manage_shares_dashboard.rst (previously: dashboard_manage_shares.rst) Yes TocTree
dashboard_manage_volumes.rst Yes TocTree
dashboard_set_quotas.rst Yes TocTree
dashboard_view_cloud_resources.rst Yes TocTree
dashboard_admin_manage_roles.rst Yes TocTree
doc/admin-guide-cloud/source/shared_file_systems_manage_shares_cli.rst shared_file_systems_manage_shares_cli.rst (previously cli_manage_shares.rst) Yes Toctree
doc/admin-guide-cloud/source/cli.rst
cli_manage_projects_users_and_roles.rst Yes Toctree
cli_admin_manage_environment.rst Yes Toctree
cli_admin_manage_ip_addresses.rst Yes Toctree
cli_admin_manage_stacks.rst Yes Toctree
cli_cinder_quotas.rst Yes Toctree
cli_cinder_scheduling.rst Yes Toctree
cli_keystone_manage_services.rst Yes Toctree
cli_manage_flavors.rst Yes Toctree
cli_manage_services.rst Yes Toctree
cli_manage_shares.rst Yes Toctree
cli_nova_evacuate.rst Yes Toctree
cli_nova_manage_services.rst Yes Toctree
cli_nova_migrate.rst Yes Toctree
cli_nova_numa_libvirt.rst Yes Toctree
cli_nova_specify_host.rst Yes Toctree
cli_set_compute_quotas.rst Yes Toctree
cli_set_quotas.rst Yes Toctree
analyzing-log-files-with-swift-cli.rst renamed to cli_analyzing-log-files-with-swift.rst Yes Toctree
networking_advanced_quotas.rst renamed to cli_networking_advanced_quotas.rst Yes Toctree
nova_cli_manage_projects_security.rst renamed to cli_nova_manage_projects_security.rst Yes Toctree
cli_overview.rst No Admin User Guide > cli.rst toctree
cli_install_openstack_command_line_client.rst No Admin User Guide > cli.rst toctree
cli_discover_version_number_for_a_client.rst No Admin User Guide > cli.rst toctree
cli_set_environmental_variables_using_openstack_rc.rst No Admin User Guide > cli.rst toctree
cli_manage_images.rst No Admin User Guide > cli.rst toctree
cli_manage_volumes.rst No Admin User Guide > cli.rst toctree

Past, Completed 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 (DONE)
  • 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. (WORKING ON) Darren Chan

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/ Merged
openstack / networking-guide Brian Moss https://review.openstack.org/#/c/224416/ Merged
stackforge / fuel-docs Brian Moss https://review.openstack.org/#/c/219069/ Merged
openstack / cinder-specs Christian Berendt https://review.openstack.org/216116 On review
openstack / nova-specs Christian Berendt https://review.openstack.org/#/c/216122/ Merged
openstack / training -guides Brian Moss Waiting for creation of new repos On hold
openstack / ironic-specs Brian Moss https://review.openstack.org/#/c/224940/ Merged
openstack / ceilometer Brian Moss https://review.openstack.org/#/c/224942/ Merged
openstack / api-site Emett Speer https://review.openstack.org/219944 Merged
openstack / ceilometer-specs Brian Moss https://review.openstack.org/#/c/224432/ Merged
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/ Merged
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 Merged
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.


User Task Matrix

Task Operators System Administrator End Users
Planning Installations 7 7 1
Networking Setup 10 10 1
Creating Projects 10 10 0
Creating Instances 10 10 2


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

Meeting Archive

Action Items

  • Thursday 15/10/15
    • Complete the Spec before Mitaka Summit - Joe - DONE
  • Thursday 01/10/15
    • Drafting Specification for M release
    • Completing minor items for L release
  • Thursday 09/03/15
    • Joe to make a new blueprint for a clean start at logging the work items now conversion is over - Joe - DONE.
  • Thursday 07/09/15
    • List the RST issues we have run into for editing so we can present our findings - Joe - DONE
    • Contact a core reviewer or RST SME for information on how to solve these issues - Alex - DONE
  • Thursday 06/25/15
    • Update Calendars and Meeting times for the next meetings - change to fortnight - Joe
  • Thursday 06/18/15
  • Thursday 06/11/15
    • Updated Documentation/Migrate wiki table for Cloud Admin Guide with Networking.xml conversion chapters marked as "On Hold" - Alex - DONE
  • Thursday 06/04/15
    • Email out request for Cloud Admin Guide repository freeze. - Brian, Joe. - DONE
    • Linking RST conversion to the User Guide improvement blueprints - Brian - DONE
    • Move HOT guide to heat repository - Brian (https://bugs.launchpad.net/openstack-manuals/+bug/1461720) - DONE
    • HowTo overhaul discussion, and HowTo for first timers. Brian - This has been taken on by a separate team

Previous agendas

  • Thursday 15/10/15
    • Docs Spec - What to include, and thoughts and ideas
  • Thursday 01/10/15
    • Priority for Liberty release - minor changes, items that can be low hanging fruit bugs. Review User, Admin User, and Cloud Admin books.
    • Spec - working on.
  • Thursday 09/17/15
    • Priority for Liberty release - Updating abstracts, Updating images of the dashboard, Consistency items.
    • Procedures with dot point items - change to a :hlist: role, which creates a shorter list - compacting information, taking less space.
    • Dev docs links to update
  • Thursday03/09/15
    • Email updates - all emails with important announcements will have " [user guides] " two words, in the subject line.
    • Fixing Links with Guide changes. There is a table for tracking these links. Most sources are updated now. Chase down any devdocs or other project links
    • Begin on work items - still need a blueprint to track bugs.
  • Thursday19/8/15
    • all the content is accounted for. Starting the change to .rst. Switching off the .xml and publishing the .rst version - Andreas has put together a list of the steps involved. There are several steps involved. He has used the security guide as an example.
    • Create a new blueprint to store work item patches. Any related bugs on changing the user, cloud admin, or admin guides, please search and add these to the blueprint whiteboard as items to work on- use Workitem tag, followed by a link to the bug.
    • "nova live migrations" and "nova zookeeper" .. todo markers are still in the docs. Can we keep the notes in the document, and then write links to these configuration reference files as a work item on the list?
  • Thursday 06/08/16
    • User Task Matrix - Use this table as a frame for reviewing the user guides. Please add tasks to the left column as you review the guides - check on procedures, and what they are asking the audience to do. The more important the tasks is to the particular user type, the higher the number.
    • Change to .rst - I have started reviewing the rst files for any leftover items to convert.
    • Task list - I have added the task list from the docs spec to the wiki as a guide. Zhu.rong has already taken a step to reorganise the content. https://review.openstack.org/#/c/205800
  • Thursday 23/07/15
    • https://review.openstack.org/#/c/199869/ - Contact zhanguoqing on the bug progress, and if they need assistance
    • User Guide Common Files - some common files attached to the Cloud Admin Guide left to convert - Decide if we should follow these up, and add them to the table. support-compute.rst is in the compute toc tree now for example - add remaining common files
    • Directions for user guides following conversion - something to start thinking about, referring to the user guide spec. (https://review.openstack.org/#/c/174647/)
  • Thursday 07/09/15
    • Tables - are the list tables building correctly - screen cap tables or code segments that were in +-----+ format.
    • Any conversion points: pandoc cut out some headings - adding them back in during review.
  • Thursday 06/25/15
    • RST check in: any questions or discussions?
    • Any returning members need an update?
    • Any bugs for cloud admin to tag, pause, or merge?
  • Thursday 06/18/15
    • Action items from last meeting - networking sections tagged
    • Networking sections updates
    • Any past items to discuss
  • Thursday 06/11/15
    • Action items from last meeting - All either Done or Doing.
    • Cloud Admin Guide RST Conversion - Hold off on converting networking sections, as these may be removed entirely
    •  :option: tagging note - :orphan: directive for common files
    • Any past items to discuss.
  • Thursday 05/28/15
    • The Cloud Admin Guide RST Conversion is now a priority follow the summit. So this crosses off a question from

two weeks ago on whether the guide was in our scope. There is a task tracking table added to the RST migration page on the Wiki.

    • There is now a new heading on the RST conversion task tracking page.
    • Question for experienced writers - Where to start from here?
  • IA Update:
    • Rename the Virtual Machine Image Guide to the Cloud Image Guide
    • Admin Guide versioning. One consideration is to add versioning to the Admin Guide
    • Move Hot Guide from End User Guide to Heat repo
    • Rewriting the How-To section, resulting in doc that has ease of readability. This must avoid duplication of the infra-manual.
Retrieved from "https://wiki.openstack.org/w/index.php?title=Documentation/ReorganizeUserGuides&oldid=122737"