[Starlingx-discuss] [docs] [meeting] Docs team notes 2020-08-12

[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-08-12 
. All -- reviews merged since last meeting:  1 

. All -- bug status -- 7 total, all low priority
   o [ww31]  Documentation regarding build-srpm.data is unclear [defer till after R4]
   o [ww30] 2: Changes in starlingx-api-ref.rst [low, WIP by Wenping Song], request to change install method (using rsync instead of STX mirror site) [defer till after R4]
   o [ww29] 2: Doc suggestions [not started-defer till after R4], Rename "active-backup" [WIP-low]
   o [ww25] Remove hardcoded "r1" in build scripts & docs [defer till after R4]
   o [ww20] Networking documentation [defer, may be resolved after WR docs are upstreamed]

. Reviews in progress:   
   o Several reviews related to Rook
 
All -- Opens
. Welcome Wind River Tech Pubs team members: Juanita, Ron, Oliver

. Regarding the Rook reviews, Ildikó made the suggestion to mark these iterative reviews with "WIP" in the beginning of the title commit message until they are actually ready for review. (Better than Workflow -1 since you have to remember to reset the W -1 each time you make a commit.) 

. Upstreaming WR docs 
   o Juanita and Ron are working on the docs and will continue to support the docs effort.
   o Oliver will be working on the process of moving from the DITA source into RST files. 
   o Expect to have more detail next week: status on plans/schedule for upstreaming the docs.

   . Will be posting reviews, etc. to follow the normal process.
   . Figure out the organization of where things will go, start smaller with ~5 reviews, figure out the batches, etc. 
   . Doing a local build of the commercial WR docs different from the STX docs, may not impact STX but need to figure out the plan.
   . Suggestion to get more reviewers to focus on this: from Intel, from WR, across the community to help with this task. Greg to get 4-5 WR, Bruce to ask 4-5 on the Intel side. 
   . Targets: next week: another update on status. Week after that they expect to start with reviews. 
   . AR Mary: Post on the mailing list & bring up on the Community call -- this is coming, we will have a bunch of doc reviews coming, appreciate your help. 
   . Focus of review? WR folks should've seen it before, so maybe presentation or diffs between STX? TBD 
   . ? about tips & tricks and pain points. Pointed to the wiki for general docs team info [https://wiki.openstack.org/wiki/StarlingX/Docs_and_Infra] and doc contributor guide    [https://docs.starlingx.io/contributor/doc_contribute_guide.html]  
   . Mary is available to help with reviews or general questions.
   . ? about graphics/diagrams. Right now, not many diagrams in STX docs, typically PNG or JPG files. We don't archive the source file. Need to come up with a process in the Upstreaming plan.
   . ? about complex tables. We don't have those in STX docs. Need to come up with a process in the Upstreaming plan.

. Version/tagging of STX docs. Still looking into how to make this work, Ildiko has another contact. We may need to create a test project, add the www/templates folder, and start deleting to see what's not necessary. 
   o For reference, OpenStack things are documented here: 
   o OpenStack doc tool scripts: https://docs.openstack.org/doc-contrib-guide/doc-tools/scripts.html
   o    repo here: https://opendev.org/openstack/openstack-doc-tools
   o OpenStack template generator: https://docs.openstack.org/doc-contrib-guide/doc-tools/template-generator.html