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

Camp, MaryX maryx.camp at intel.com
Thu Jun 25 18:12:24 UTC 2020


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-24  
. All -- reviews merged since last meeting:  5
. All -- bug status -- 10 total, 4 WIP
	o [ww26] 1 new: update the build guide for STX R3.0  AR Mary reply to Poornima, clarify the issue. Should we point to release notes for version info? 
	o [ww25] 2: Change $Home in build docs and Remove hardcoded "r1" in build scripts & docs
	o [ww24] 2: Document build-pkg command [WIP] and Document packaging esp. build-srpm.data
	o [ww23] Fix search function. [WIP] First review enabled search of OpenStack docs: https://review.opendev.org/#/c/733383/  [Cross job to test changes: https://review.opendev.org/#/c/733483/]
	o [ww23] Add instructions for building stx-openstack application [WIP]  OK to merge? Ping Saul, wait 24 hours, then merge.
	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.  OK to merge? Ping Saul, wait 24 	hours, then merge.
	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 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 -- R4 target content: https://storyboard.openstack.org/#!/story/list?status=active&tags=stx.4.0&project_id=1046
	o Assignment of R4 doc tasks
	. These stories have no assigned person:   
	. https://storyboard.openstack.org/#!/story/2007222 (update dist cloud bare metal install w/ redfish info)  AR Mary check discuss archive, may be covered already? If not ask Tao Liu. 
	. https://storyboard.openstack.org/#!/story/2006588 (updates for Dist Cloud)  AR Mary ask Dariush (reference the story) Do we need doc updates?
. All -- Opens
	o Search functionality priority 1 -- must be fixed for R4. AR Mary follow up with Ildiko and the OpenStack folks who helped with theme update. 

. Short discussion about future planning:  [17Jun20] keep here for reference.
	. 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. 




More information about the Starlingx-discuss mailing list