[Starlingx-discuss] [docs] [meeting] Docs team notes 15-Sep-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
==========
15-Sep-21
All -- reviews merged since last meeting:  7  Most are in R5 branch.    
      
All -- bug status -- 19 total - team agrees to defer all low priority LP until the upstreaming effort is completed. 
7 LP are WIP against API documentation, which is generated from source code (low priority). 

2 new LP this week. Still having the situation of duplicated issues in Jira (downstream) vs LP (upstream) and how to track them. 

Retrospective - the WR team had 2 sessions. One of the items for docs: 
Discussion about traceability for doc issues that were reported downstream and fixed in the upstream. 
   If you aren't the issue owner/raiser, there isn't good tracking. 
   Customer reported issues may need improved tracking and traceability. 
We will continue to discuss the feedback, and figure out actions. 

Discussed R6 vs R5 install guides in master/working branch
   We are currently maintaining 3 folders of install guides (R5 and R6 in master, R5 in R5 branch). 
   How can we reduce all the overhead involved with that? Are the R5 changes slowing?
   What if we eliminate R6 folder now, then maintain r5 folder in master and cherry pick to R5 branch. 
   Will users notice R6 is moved? Add a redirect/explanation?
   Definitely we want to be aware of this for next release cycle, we don't want to make the R7 install folder right away. 
   Right now the R5/R6 files are nearly identical, just the labels are different. 
   If we could figure out a way to make a wrapper around the r5 docs, then it would solve the problem. 
   Is it too close to R6 to mess with this?
   We don't want to do a ton of work now, then have to undo it next week or whenever the R6 install changes start coming...

Segue into:   doc organization - most of the guides have 2 big directories:  Kubernetes and OpenStack 
Contents section - makes sense in the upstream, but sort of meaningless to downstream users. 
    Would be helpful to make the contents in an include file so it is removed from the downstream files. 
    This change is coming soon, Ron will submit reviews. 

One more item, we aren't making a decision today:  rethinking how the downstream builds work. 
   part of the new/improved solution will be:  make all filenames unique (now it is tricky with "overview.rst" in different folders)
   possibly create a utility to make a stub file with a guaranteed unique id -- would spit it out for you. 

Future discussion: Retiring the docs that are not required in the downstream / replacements.