[Starlingx-discuss] [docs] [meeting] Docs team notes 20-Jan-21 DRAFT

Camp, MaryX maryx.camp at intel.com
Thu Jan 21 01:49:15 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
==========

20-Jan-21 
All -- reviews merged since last meeting:  3
All -- bug status -- 19 total - team agrees to defer all low priority LP until the upstreaming effort is completed. 
   13 LP are WIP against API documentation, which is generated from source code (low priority). Those reviews are here: https://review.opendev.org/#/q/project:starlingx/config
   1 new LP is a minor doc change that Mary will do.

Discussion
SNMPv3 doc updates - should we do them now? Yes, OK to do this now. Juanita's going to do this. 

Ron submitted a new review for Planning Guide, this adds OpenStack content. It's ready for reviews. The goal is to get it merged and then it will be used to figure out the downstreaming process. 

Restructuring due to OpenStack additions. Right now, all of the guides that have been upstreamed have 1 index file, needs to be restructured with folders for Kubernetes and OpenStack, which means 2 new index files.
For an example of this, see the planning guide review (https://review.opendev.org/c/starlingx/docs/+/771700)
We viewed the output and decided to look into making expandable sections (like the "Detail" option in the API documentation https://docs.starlingx.io/api-ref/stx-config/api-ref-sysinv-v1-config.html#system)
Ron - thinks div would be needed, will look around to figure out how to do it. 

As another option, we talked about reorganizing the upstream docs so they are split at the top level: StarlingX > Kubernetes or OpenStack
Ron doesn't think there's a lot to be saved from doing this. Decided not to do this for now. 
What do users want: some users need lots of help just figuring out StarlingX and some users are figuring it out on their own, know about Kubernetes and OpenStack.
 
Could we add breadcrumbs (where you are in the TOC) along the top to help users? Is it a Sphinx plugin we could add?
Mary ask Kevin next week. Juanita shared that Red Hat and WRCP docs do this also.
https://access.redhat.com/documentation/en-us/red_hat_openstack_platform/16.1/html/release_notes/chap-introduction#database_size_management

Helm v3 email from James Gauld (update to https://docs.starlingx.io/admintasks/kubernetes-admin-tutorials-helm-package-manager.html)
* Need to check - we think that Helm v3 was done in StarlingX but not WindRiver Cloud Platform, so this change needs to be made in docs.
* The change should come through as part of the upstreaming and resync to latest snapshot. Hold off now from making this change. Revisit in the next couple weeks. 

Version drop-down update from Mary - Kevin Putnam from Mike Tullis' team is digging into this, he says it's an interesting issue. 
* He plans to review the current OpenStack-based theme and simplify it where possible, to be easier to maintain and update afterwards. 
* As we discussed before, we'll need to restructure a little. Now all the doc content is at the top of the domain. 
* The button for latest goes to https://docs.starlingx.io/latest (which doesn't currently exist, so 404 error) 
* Suggestion to implement this structure, so that all existing/incoming links to starlingx.io will not break.   
   https://docs.starlingx.io/        << add a redirect here to send to /latest              
       /latest     
       /R5.0     
      /R4.0          
* Mary to confirm that the doc repo branching is exactly the same as the software nomenclature and branching. 




More information about the Starlingx-discuss mailing list