[Starlingx-discuss] [docs] [meeting] Docs team notes 2020-06-17

[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]   Our tracking Etherpad: https://etherpad.openstack.org/p/stx-documentation 

thanks,
Mary Camp
==========
2020-06-17 
. All -- reviews merged since last meeting:  6
. All -- bug status -- 9 total, 3 WIP
    o [ww25] 2 new: Change $Home in build docs and Remove hardcoded "r1" in build scripts & docs
    o [ww24] 3: Document build-pkg command, Document packaging esp. build-srpm.data, Add new CLI for reconfiguring subcloud [WIP]
    o [ww23] Fix search function. Update from 17Jun20: Jimmy from OpenStack suggests merging Ildiko's reviews to see if that fixes it. Change scope of search bar: https://review.opendev.org/#/c/733383/  and Cross job to test changes: https://review.opendev.org/#/c/733483/
    o [ww23] Add instructions for building stx-openstack application [WIP]
    o [ww20] Networking documentation [not started]
    o [ww16] Build Avoidance [WIP] https://docs.starlingx.io/developer_resources/build_guide.html#build-avoidance)

. Reviews in progress:   
    o Layered Build guide (Poornima). Email questions about why this doc is needed. AR Mary reply to email thread, propose title change "Layered Build Reference" for Scott's original guide.
    o Chinese document for layered build https://review.opendev.org/#/c/726737/  Yong Fu has made changes. Requested Yi Wang / Austin to give technical +1 before merge.
    o Rook migration editorial  NOT officially in r4.0 but code will merge quickly afterwards. AR Mary figure out how to handle. Should be tied to the code merge -- Orig review 723291 has link to story https://storyboard.openstack.org/#!/story/2005527
    o Kubernetes policy guides
    o Add how to access STX OpenStack CLI
    o Modifying layered build commands (add pike / remove pike)  This review is valid for the current situation: https://review.opendev.org/#/c/717424/ 
        . Saul's review is valid for "future" situation -- we think will be merged in next couple of weeks https://review.opendev.org/#/c/693761/ 

. All -- Opens
    o FYI: The "submit a bug link" on the doc pages points to LP now, hooray!
    o Bruce noted issue with code samples display problems. Color coding of  . or - in snippets makes it hard to read. AR Mary investigate. [After meeting, verified this is due to recent change to openstackdocs theme]
    o Short discussion about future planning:
        . 1. After R4 release, we will branch the documentation. This will get docs set up for item 2.
        . 2. Upstream the Wind River Cloud Platform docs. This activity is still in planning/resource gathering stage. 

. Branching the STX Docs - notes from discussion 20May20 - keep here for reference.
    o Recommendation from Bart to plan a method for versioning the documentation. The current approach has these issues:  
        . People are making updates to the docs for previous releases in the master branch, but not in the release branch. So if someone goes to look at the docs in the r/stx.3.0 branch, they will get stale info.
        . Our docs web site does not allow users to see info for previous releases for some areas. For example, our REST API  Reference (https://docs.starlingx.io/api-ref/index.html) is just showing master (I think). To see the r/stx.3.0 REST APIs, the user would have to go to each repo (e.g. metal, config, nfv) and choose the branch there. That isn't a good way to access these docs.
        . Now we only build the master version of docs. We want to change that for future. We want the web page to allow selecting different versions like the examples above. 
    o Our plan is to keep updating docs in master like we're doing now. After R4 is released, then we'd create an R4 branch and cut over to the new method. 
        . Ask Scott/Saul to include docs in branch process when they do it. [We think they're doing this already, because someone created an r/stx.3.0 branch.]
        . Once we have 4.0 branch, delete all the old release folders and have only one version of the docs that we keep up to date. 
        . The existing R3 branch is just a throwaway because it's not updated at all. [Delete old branches, unversion the current branch.]
        . After this is implemented, if master is updated with something that applies to previous releases (like a bug fix), you'd have to make a similar change in the specific branch. 
    o We need to plan this transition. We need help to implement the web changes.
        . Docs for other OpenStack projects allow you to switch between versions: https://docs.openstack.org/horizon/train/ (version switcher), https://docs.openstack.org/ironic/latest/index.html (switch in URL, w/ explanation), https://docs.openstack.org/keystone/latest/install/index.html (switch in URL)
        . AR Mary: Follow up with Ildiko on versioning/branch the docs for better usability. Need web developer help to implement these changes. Suggestions?