[Starlingx-discuss] [docs] [meeting] Docs team notes 09-Mar-22

Camp, MaryX maryx.camp at intel.com
Wed Mar 9 22:09:43 UTC 2022


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
==========
09-Mar-22 

Reviews merged since last meeting: 8  

Cherry pick discussion: No cherry picks this week.

Status/questions/opens

Mary transitioning off of StarlingX, effective 23Mar22

* STX Docs Project Lead Role and Responsibilities - https://etherpad.opendev.org/p/docs-transition-plan  
* Run the meeting, post the notes to discuss list, send the calendar appointment
* Self-nominate for the role: https://docs.starlingx.io/election/#how-to-submit-a-candidacy and https://docs.starlingx.io/election/#election-officials
* Here is the review I did back in November to use as a model: https://review.opendev.org/c/starlingx/election/+/816172
* Greg will reach out to Ildiko about changeover process. 
* ARs to update Gerrit starlingx-docs-core-members: https://review.opendev.org/admin/groups/a5855cd3493dd77715830eb523c6b2ad43ccac5c,members
* STX Wiki: https://wiki.openstack.org/wiki/StarlingX/Docs_and_Infra 
* Admin tasks etherpad explains what happens at release time: https://etherpad.opendev.org/p/stx-doc-admin
* Upcoming PTG meeting - April 4-8 - Greg can help with what's expected.
* PTG Planning etherpad here:  https://etherpad.opendev.org/p/stx-ptg-planning-april-2022


Jeremy's message on STX Discuss list:  http://lists.starlingx.io/pipermail/starlingx-discuss/2022-March/012822.html

Is there anything we need to do about this? Ron says no, this doesn't apply to our tox.ini file. No changes needed.


Standard for representing variable version numbers, i.e. nn.nn vs xx.xx vs     <nn.nn> vs <xx.xx> etc 

We want to reduce maintenance and not have to update version numbers each time. Do we prefer nn vs xx?  nn is preferred.
We would like the pattern to match the context -- if we are showing 21.12 as nn.nn, then we should also show 21.12-01 as nn.nn-nn
Add a note to the Usage guidelines?
Perhaps add a caveat, something like: 
Be aware that examples in this guide may show a version number that is different from the current release. See the Release Notes for information on the current release.


Maintaining FM events and alarms 

events.yml gets updated every release. Instead of updating so many doc files, suggest to annotate the yml file itself, add legend, etc. 
But what if the user doesn't have internet access to get the link? Maybe deliver the HTML as a bundle. 
Maybe write a script to process the events.yml to export it into a documentation-friendly format?
Use the API publishing mechanism as an example?


Tabbed content

This would be great to improve the user experience. 
Ron is testing an open source plug-in for Sphinx that can do the tabs. 
It is a calculated risk to try a free tool, but this one seems stable, has been updated recently, and has an active user community.





More information about the Starlingx-discuss mailing list