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

[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-21
All -- reviews merged since last meeting:  1
All -- bug status -- 18 total - team agrees to defer all low priority LP until
the upstreaming effort is completed.

Virtual PTG next week 
Project Teams Gathering (PTG) for Open Infrastructure Foundation (formerly Open Stack Foundation) takes place next week.
The STX slots are Tues and Thurs 6-10 am Pacific next week.
Details including how to register and schedule are here:
http://lists.starlingx.io/pipermail/starlingx-discuss/2020-October/009757.html  
We will hold Docs meeting next week so we don't lose momentum on the upstreaming. 
AR Mary create 1-2 slides to talk about our plans to upstream Wind River docs.

Using inclusive language 
http://lists.starlingx.io/pipermail/starlingx-discuss/2020-October/009820.html
The guidelines specifically mention these terms for special attention: master/slave and blacklist/whitelist 
"master" in the context of master branch is still WIP at the OpenStack level, so no action required at this time.

STX docs - I searched across the RST files "master" in the context of controller/master node, build (master branch), grandmaster
clock - 119 instances - most "master branch" or "/master" in path or command line  ~15 instances node-related 
"slave", "whitelist", and "grandmaster clock" in Time-Sensitive Networking (TSN) - 2 instances of each - 6 instances total
AR Mary look into updating TSN guide. 
no instances of blacklist

WR docs - I searched Wind_River_Cloud_Platform_Concatenated_PDF_20.06.pdf
"master" used as controller/master nodes, master Ansible playbook - 38 instances
"slave" in the context of Precision Time Protocol (PTP) and Link Aggregation - 12 instances
no instances of blacklist/whitelist

The team agrees that where "controller/master" is used - could probably change this text to "controller", however it will depend on the context. When "master"
is used in menus/displays, it might need to stay. 
Going forward, the team will look for areas for improvement. 

Upstreaming WR docs  

Status: 3 folks working on the upstream/conversion. Ron has worked with Greg and Bart on Node Management guide and updated reviews should be
coming by end of week.

Using only and include directives 
Last week we discussed how to 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.  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] 
After testing it, Ron came back with a modified proposal to have one _includes dir at the top of the tree as a central location for all
include files. The difference will be that the include statements will point up the tree, not down.  
For example: 
.. only:: partner
 
   .. include:: ../../../_includes/about-host-memory-provisioning.rest
   
Team agreed with this approach.    

Using Rubrics:  this keeps headings from being captured in TOC 
The class for rubrics is defined in basic.css, provided by Sphinx. 
However, the StarlingX templates don't load that file, and we probably don't want to as it contains
other definitions that may conflict with customizations.
 
Shared OpenStack/StarlingX customizations seem to live in
https://opendev.org/openstack/openstackdocstheme/src/branch/master/openstackdocstheme/theme/openstackdocs/static/css/combined.css.

Not sure if you want to make changes to a file that is shared with OpenStack. 
If not, there is also the folder https://opendev.org/openstack/openstackdocstheme/src/branch/master/openstackdocstheme/theme/starlingxdocs/static/css.
A new file could be added there. It would just need to contain something like:
 
p.rubric {
  margin-top: 30px; 
  font-weight: bold; 
}
 
STX docs are still tied to the openstack theme and the WIP review to create a standalone STX theme is stalled.  
Next step:  create a review to implement this in openstackdocstheme repo and try it out. 
This etherpad describes how to test out theme changes locally: https://etherpad.opendev.org/p/Testing_repos_theme_locally

Complex tables 
Ron provided 2 examples of how to handle the complex tables. The team liked the 2nd option better (series of simple tables) as long as they're
not too much extra work to create. Sample uses list tables (explained here: https://docs.openstack.org/doc-contrib-guide/rst-conv/tables.html#list-tables)

Display multiple versions of STX docs - no update.