[Starlingx-discuss] [docs] [meeting] Docs team notes 2020-09-02

[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-09-02 
All -- reviews merged since last meeting:  1 
All -- bug status -- 6 total - team agrees to defer all low priority LP until the upstreaming effort is completed. 

Reviews in progress:   
	Several reviews related to Rook are ready to review per discuss list message: http://lists.starlingx.io/pipermail/starlingx-discuss/2020-August/009452.html
	Pinged Martin Chen to respond to review comments for these reviews: https://review.opendev.org/#/q/status:open+project:starlingx/docs+branch:master+topic:ceph-cluster-editorial

All -- Opens
Can the test team be looped in to test some of our complicated procedures (ie install/deployment guides)? Greg and Mary attended Test meeting this week.
	Propose we use launchpads for test request. Greg/Mary to create launchpads for explict testing, and provide query to test team.    
	Test team will review the backlog and have them discussed and assigned in test meeting.   

Upstreaming WR docs status
	Multiple WIP reviews now. 
	Substitutions file -- https://review.opendev.org/#/c/748747/  Ron will resubmit patch without the switch -- team agreed to use 1 strings file and agreed to the suggestions in the strings file.
	General discussion about strings/substitutions: 
		Need to be sure that any non-STX doc builds don't replace the existing copyright/legal statements that refer to STX. 
		As we upstream docs, be aware about replacing WR (or removing naming entirely) in the STX docs. 
	Ron to check with Drake and Keane if their reviews are ready for actual review or still in testing mode.
	Still fiddling with the generator that will do bulk of the work. Goal is to have tool do more of the grunt work (manual search & replace, etc). Another update next week. 
	Keep submitting reviews in small-ish chunks to be sure we catch any generator issues. 

Display multiple versions of STX docs
More messages with Jeremy Stanley on discuss list, portions copied below for convenience during meeting discussion:

http://lists.starlingx.io/pipermail/starlingx-discuss/2020-August/009530.html 
That entire extension is, quite frankly, full of OpenStackisms. I can imagine two solutions to this: expand the extension's scope or fork it. I suppose there's also a middle ground where we extract the OpenStackisms 
from ext.py into a separate replaceable module and then we'd only need to fork that module. I'll see if anybody in the OpenStack Technical Writing SIG has an opinion on whether the scope expansion or refactoring 
solutions would be acceptable to them, since they're co-maintainers of openstackdocstheme (along with the OpenStack Oslo team). Ultimately, though, if you're considering eventually forking all of openstackdocstheme
anyway, this might be the change which pushes that decision over the edge.

Team discussion: 
Ildiko pointed out that the OpenStack theme is more "locked" and harder to tweak, it needs to be released for any updates. Our theme could be more flexible if it was completely our own. Bruce agrees.
OpenStack folks are more involved with infra/tools because it's more complex. Our needs will be simpler for the most part, even long term. 
AR Mary to reply to Jeremy that we want to implement the fork option. 

http://lists.starlingx.io/pipermail/starlingx-discuss/2020-September/009543.html 
> The STX docs repo already has an R4 branch:
> https://opendev.org/starlingx/docs/src/branch/r/stx.4.0  so that part 
> is done. Our planned URL structures are:
> https://docs.starlingx.io/R4.01 (current release) and 
> https://docs.starlingx.io/latest for the master branch.
[...]
 
In drafting https://review.opendev.org/749369 to implement this alternative matching, it has dawned on me that I'm not entirely clear from the above what your expectations are when publishing. In short, are you publishing from a branch or from a tag? If the former, then the r/stx.4.0 branch's documentation would presumably be published under R4.0 not R4.01. Was that a typo, or is there some missing bit of detail to determine the publication directory from the branch?

AR Mary to reply to Jeremy: We want to publish from a branch (not tags) and use the branch naming convention.