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

[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-26 
All -- reviews merged since last meeting:  4 + same ones were cherry-picked into R4 branch
All -- bug status -- 7 total - team agrees to defer all low priority LP until the upstreaming effort is completed. 

All -- Opens
Can the test team be looped in to test some of our complicated procedures (ie install/deployment guides)? Greg and Mary will attend the Test meeting and ask them about it. [Next meeting 1Sept @ 8 am PDT]

Upstreaming WR docs status:
   First trial review submitted last week. Still messing around with the script/tool output. 
   Another user has a book that's converted and ready to submit. Requirements: should have a successful local build (tox -e docs) and review of the HTML for general structure/formatting.
   Then OK to submit review, start with 15-20 topics (couple chapters). 

Conversion questions for WR docs:
1. TOC structuring - current source in DITA is much more granular (smaller pieces). 
Many little pages vs fewer large pages vs combo.  Easiest to start with is many little pages with nested index files - but may not be best for user - we can ask for community input on the review. 
3 options: 1 index per chapter, merge into 1 chapter per file, or take the existing output and just list them out (no heirarchy)

2. Terms that will differ between STX and reimport to WR, e.g. "StarlingX" vs "Cloud Platform"   aka how to handle product names. Need a variable/parameter setup. CMS uses a key-def file now. 
Sphinx calls this substitution:  https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#substitutions  
Format like this:  .. |STX| replace:: StarlingX  
Create a substitutions.txt file. Edit the conf.py file to reference the substitutions file. Use rst_prolog or rst_epilog to implement.
Ron is working on this now, he can do pre-work on the DITA side to make it work on the export. The "only" directive could be used to build WR vs STX docs.
Submit a review with the proposal -- common folder to be added to capture substitutions. 

3. Should reviews be submitted on a specific branch?
Work in progress should be done in a branch of your local master. When you submit a review, it is against the master branch.

4. File naming convention
CMS uses letters/numbers in current filenames, the conversion tool is translating into words with hyphens. 
Current STX convention uses lowercase words separated by underscore. Team agreed that hyphens are OK.

5. Screenshot location (./figures or somewhere else such as /screens?)
Place in a /figures folder to align with current docs. 

Version/tagging of STX docs 
Jeremy replied to discuss list (http://lists.starlingx.io/pipermail/starlingx-discuss/2020-August/009471.html) with recommendations.
Mary suggests we follow the 2nd option he mentioned - project-specific model and branch the docs when the other STX repos branch. 
STX docs repo already has R4 branch like this:  https://opendev.org/starlingx/docs/src/branch/r/stx.4.0
Possible URL structures:  https://docs.starlingx.io/R4.01 (current release) and https://docs.starlingx.io/latest for the master branch.
Team agreed with this suggestion.