[Starlingx-discuss] [docs] [meeting] Docs team notes 2020-10-14

[Camp, MaryX]

Hello all,
Here are this week's docs team meeting minutes (short form). Details in [2].
Join us if you have interest in StarlingX docs! We meet on Wednesdays 12:30 PST.

  [1]   Call logistics: https://wiki.openstack.org/wiki/Starlingx/Meetings 
  [2]   Tracking Etherpad: https://etherpad.openstack.org/p/stx-documentation 

thanks,
Mary Camp
==========
2020-10-14 

. All -- reviews merged since last meeting:  0  
. All -- bug status -- 12 total - team agrees to defer all low priority LP until the upstreaming effort is completed. 
   o 2 more LP submitted by https://launchpad.net/~leiyuehui against API documentation, which is generated from source code. (6 total, low priority).   AR Mary follow up with submitter.
. Reviews in progress:   
   o Several reviews related to Rook are being worked: https://review.opendev.org/#/q/status:open+project:starlingx/docs+branch:master+topic:ceph-cluster-editorial
   o Scott's review, part of the debranding:  https://review.opendev.org/#/c/757932/  

Upstreaming WR docs status

. Display issues with code samples and scroll bars. We discovered that missing scroll bars in wide tables and code snippets were browser discrepancies, not Sphinx issues. Can't find an official browser support statement in StarlingX, but did find one for OpenStack Horizon: https://docs.openstack.org/horizon/latest/user/browser_support.html  Ron has Firefox, so does Greg. Don't need to create a whole test plan for multiple browsers, keep an eye on upstream look and feel during conversion. Team agreed to add a statement something like this:  StarlingX documentation is best displayed using Firefox and Chrome browsers. Other browsers may not display certain template formatting.

. We are using 'rubrics' now to include subheaders in tasks, such as "Prerequisites", "About this Task", "Procedure" etc. This prevents them from being captured in the TOC like 'normal' headers. But they render as plain paragraph text in tox builds. Looking at the source for an example, I see that we have a class:  <p class="rubric">Procedure</p> but it does not seem to be defined in the StarlingX templates. Likely to be defined in a stylesheet, figure out which one is loaded onto the page. << AR Mary and Ron look for this. Possible locations below.
   o OpenStack doc tool scripts. Overview here:  https://docs.openstack.org/doc-contrib-guide/doc-tools/scripts.html, repo here: https://opendev.org/openstack/openstack-doc-tools
   o OpenStack Docs Theme. Overview: https://docs.openstack.org/openstackdocstheme/latest/, repo here:  https://opendev.org/openstack/openstackdocstheme/src/branch/master
   o OpenStack template generator. Overview: https://docs.openstack.org/doc-contrib-guide/doc-tools/template-generator.html, repo here:  https://opendev.org/openstack/openstack-manuals/src/branch/master/www/templates
 
. We have some very complex tables, for example, for alarm and event definitions. The spans in these seem to confuse the StarlingX table templates that control row background color alternation (white, grey, white ...). See the attached screen. Not sure what the solution is here. The information may need to be refactored to avoid this behavior. 
   o The alternating color rows are mixed up. Can we turn that off? May be other options to resolve this. Ron will dig into it and report back. 

. Dealing with content that is both upstream/downstream. How should we handle content that is WR-specific but embedded in shared files? For example, a topic has a feature with subsections and 1 of them is a WR-only item. May use includes or other tags to work around this. Ron showed us a potential implementation of this, using the .. only directive [display only if docs are built using the "partner" flag] and .. include directive [include the appropriate RST file]
   Directives will be placed at the end of a file. The team agreed this is a good approach. The folks doing the conversion will implement this and we can review it. 

. TOC mapping discussion (updated doc from Juanita) - The text in purple indicates new topics, since Greg created the comparison docs with an earlier release of WRCP.  Greg had to drop off our call for another meeting. Greg may be unavailable to do a complete review of the doc set to evaluate all the new topics. Maybe he can focus on the topics in purple (identified as questions). WR has the lead on this and willl let us know if we can help. AR Juanita to bring up at their Friday meeting. 

. Related topic to bring up with Greg on Friday:  We want to discuss the features/functionality of STX December release as compared to the WRCP GA release also in December. This may impact which doc content is published on the STX website. For example, if GA release supports a feature that is not supported on STX, then we wouldn't want to confuse STX users by describing it. Discuss with Greg and team about the best way to align content with functionality. 

Display multiple versions of STX docs - no update.