Difference between revisions of "Documentation/ReorganizeUserGuides"

Revision as of 05:42, 12 November 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:

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)
  • https://review.openstack.org/#/q/status:open+topic:separate-user-guide,n,z
• 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

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

• Reorganize User Guides for Liberty Spec associated with the Reorganise User Guides Blueprint.
  • Link: https://wiki.openstack.org/wiki/Documentation/Migrate

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 12/11/15
  • Change to IRC meetings and log meetings using MeetBot
  • List meeting information in IRC meeting repo (similar to the Install Guide team)
  • Maintain agenda only for next meeting
  • Clean up our team page (https://wiki.openstack.org/wiki/User_Guides)

• 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 06/04/15
  • Cloud Admin Guide RST Conversion
  • Cloud Admin Guide bugs: This one https://review.openstack.org/#/c/187339/5
• IA Update post conference.

• 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.

• Thursday 05/14/15
  • Will the scope include Cloud Admin Guide alongside the User and Admin Guides?
  • The tasks tracking page is now active: https://wiki.openstack.org/wiki/Documentation/ReorganizeUserGuides
  • https://review.openstack.org/#/q/status:open+branch:master+topic:separate-user-guide,n,z : A list of patches to review as a priority to.