[Starlingx-discuss] [docs] [meeting] Docs team notes 26-May-21

Camp, MaryX maryx.camp at intel.com
Thu May 27 02:15:20 UTC 2021


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

Status/questions/opens

R5 readiness/status
Release Notes are ready to publish [Edge Worker doc hasn't merged yet, will uncomment the link when it does.] 
Review to update the StarlingX landing page and install guide index: https://review.opendev.org/c/starlingx/docs/+/793093

How to resolve comments that come in on reviews which have already merged
Push back that they need to give feedback in Jira or Launchpad.
How to tracking new comments in old merged reviews: in the new review, link to the older review in the commit message.

Making R6 folder for Install guides
When there's a new STX release, we usually copy/rename the latest Install Guide folder for the next release. In this case, I'd copy the R5 folder, rename it R6, and update the "R5" instances in text to R6.
I tried doing that but got about 15 warnings about duplicated labels. 
   Example:  
    file >  \doc\source\deploy_install_guides\r5_release\ansible_bootstrap_configs.rst  has this label at the top:       .. _ansible_bootstrap_configs:
  When I copy/rename the r5_release folder to r6_release, then there are 2 files with the same label.
Need to discuss how to resolve and I will add the R6 folder in another review. 

During the meeting, the team agreed that since we have implemented the version picker (allows readers to select latest and R5) we don't need to carry forward all of the old release installation guides in the Latest branch. We agreed to make these changes to the install landing pages:

On the Latest install landing page:  
We will only list the R6/latest installation guides. We will point to the version selector for readers who are looking for R5 or older install guides. 
Mary will update the doc review in progress for this:  https://review.opendev.org/c/starlingx/docs/+/793093
Mary will also create the R6 folder and append -r6 to the existing labels to fix the duplication issue. 
 
On the R5 install landing page (R5 branch):  
We will list the R1-R4 archives and the R5 links. Nothing about "latest/upcoming" release.
Mary will create a new review for this. 

Edgeworker node review https://review.opendev.org/c/starlingx/docs/+/774595
This review contains 7 :doc: references which are problematic for downstreaming. We want to use :ref: as a general rule. 
Can we merge as-is? Then Mary will make a new review that: adds label to the main file, replaces the :doc: with :ref: to label, wrap the notes in "starlingx" condition, and miscellaneous text/formatting edits.
The team agreed. New review is: https://review.opendev.org/c/starlingx/docs/+/793257

R5 Retrospective 
Collect feedback now for discussion in a future meeting?  
One item is creating a better cherry picking process -- does it matter the order of merging? how to avoid conflicts, etc.
The team agreed to discuss this after the WindRiver GA date, currently 15June21
We will dedicate most or all of the docs meeting to this topic. 
   
Docs style guidelines
Related to retrospective - we will capture suggestions with retrospective - can do separate meeting for this also.




More information about the Starlingx-discuss mailing list