Jump to: navigation, search

Difference between revisions of "User Guides"

(→‎RST Conversion Issues)
Line 94: Line 94:
 
*Pandoc conversion problems.
 
*Pandoc conversion problems.
 
**When converting files with Pandoc, some entries in the .xml file will not convert accurately. Procedure titles and sub section titles will not parse correctly, and will be deleted from the converted document. Pandoc also removes procedure numbering. Currently, the solution is to compare the complete .rst file to the built .xml version, and check the headings, subheadings, and procedure numbers to make sure they are correct, and line up with original. This is an issue that could also be discussed.
 
**When converting files with Pandoc, some entries in the .xml file will not convert accurately. Procedure titles and sub section titles will not parse correctly, and will be deleted from the converted document. Pandoc also removes procedure numbering. Currently, the solution is to compare the complete .rst file to the built .xml version, and check the headings, subheadings, and procedure numbers to make sure they are correct, and line up with original. This is an issue that could also be discussed.
 +
 +
*Contact details for RST issues that we can't solve:
 +
** Author: David Goodger
 +
** Contact: docutils-develop@lists.sourceforge.net
  
 
== Team members ==  
 
== Team members ==  

Revision as of 02:14, 9 July 2015

Welcome to the home page for the User Guide Specialty Team!

About the User Guide team

This team is all about the users. Its purpose is to give us a space to have conversations about enterprise content, support companies who reuse upstream content from the guides, and also get some focus on information architecture, consistency, and conventions in the guides.

We focus on:

  • Cloud Admin Guide (migrating to RST)
  • End User Guide (migrating to RST)
  • Admin User Guide (migrating to RST)

For the Install Guide and the Networking Guide, see those respective speciality groups.

Quick links

Housekeeping

Meetings

Meetings are held on fortnightly on Wednesdays at 23:30 UTC (Thursday 9:30am Australian Eastern Standard Time or GMT+10, Wednesday 4:30pm Pacific Standard Time), on Google Hangouts. If you're not on the google calendar invitation list and want to be, please make yourself known to Joseph or Brian through IRC or the Openstack-Doc mailing list.

Action Items

  • Thursday 07/09/15
    • List the RST issues we have run into for editing so we can present our findings - Joe
    • Contact a core reviewer or RST SME for information on how to solve these issues - Alex
  • 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 from heat repository - Brian (https://bugs.launchpad.net/openstack-manuals/+bug/1461720)
    • HowTo overhaul discussion, and HowTo for first timers. Brian

Agenda for next meeting

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

RST Conversion Issues

  • RST issues in converting tables when tables are codeblocks.
    • RST documents impose a 79 character limit when building files in .rst format. When tables exceed that limit, a list table role can help create content in a new table without exceeding the character limit. The issue is when a table is generated by an OpenStack service, and returned as a result of a command. These tables are constructed with +, -, and | characters. The table created by a list table role has solid lines forming rows, columns, and cells. The content is similar, however users might be surprised by a table with solid lines rather than a table built with +, -, and | characters. Is there a role or other filter than can be applied to list tables to make them appear as a table that might turn up in code block (+--------+)?
  • Large scale content inside tables.
    • When building tables with a list table role, some items that appear inside the table cells might exceed the 79 character limit. Is there a solution to recreating this large scale content in a table such that it does not affect the character limit?
  • The :orphan: role and references.
    • Files with an :orphan: role at the top of the file, not included in the toc tree, will not link to another file when the :ref: role is used to link to the file from a different file. Is there a solution to this linking issue?
  • Pandoc conversion problems.
    • When converting files with Pandoc, some entries in the .xml file will not convert accurately. Procedure titles and sub section titles will not parse correctly, and will be deleted from the converted document. Pandoc also removes procedure numbering. Currently, the solution is to compare the complete .rst file to the built .xml version, and check the headings, subheadings, and procedure numbers to make sure they are correct, and line up with original. This is an issue that could also be discussed.
  • Contact details for RST issues that we can't solve:
    • Author: David Goodger
    • Contact: docutils-develop@lists.sourceforge.net

Team members

  • Brian Moss, Rackspace, Brisbane Australia (UTC+10)
  • Joseph Robinson, Brisbane Australia (UTC+10)
  • Tanja Roth, SUSE, Germany (UTC+1)
  • Bernd Bausch, Japan. Not quite certain yet to what extent I can contribute.
  • Deepti Navale, Red Hat, Sydney Australia (UTC+10)
  • Alexandra Settle, Rackspace, Brisbane Australia (UTC+10)
  • Darren Chan, Rackspace, Canberra Australia (UTC+10)
Retrieved from "https://wiki.openstack.org/w/index.php?title=User_Guides&oldid=85466"