[Starlingx-discuss] [docs] [meeting] Docs team notes 2020-05-20

Camp, MaryX maryx.camp at intel.com
Thu May 21 21:14:22 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-05-20  
. All -- reviews merged since last week:  5
. All -- bug status -- 8 total, 4 WIP
	[ww21] https://bugs.launchpad.net/starlingx/+bug/1879632  DOCS: Optional filesystem for cinder image conversion. AR Mary add guide to Openstack config section > new bullet for Cinder > alphasort OK
	[ww18]  admin endpoints in distributed cloud are changed to https [WIP]
	[ww17]  Debug guide [not started] 
	[ww16]  Kata containers [WIP, location under Kubernetes operations] and Build Avoidance (not started; AR Mary compare bug text to existing guide 	here: https://docs.starlingx.io/developer_resources/build_guide.html#build-avoidance)
	[ww15]  Backup & restore procedure info [WIP, review here:  https://review.opendev.org/#/c/721772/] AR Mary minor text edits then ready to merge 

. Reviews in progress:   
	o Chinese document for layered build https://review.opendev.org/#/c/726737/  Mary sent email to discuss list last week, not much response. In today's meeting we discussed our concerns about maintenance, ensuring 	accuracy, etc. But we also don't have Internationalization team to handle this. We agreed to accept the review and add an English note at the top stating something like: "STX doesn't have a translation project team and 	this guide may not be actively maintained. Please contact the StarlingX docs team [link to https://wiki.openstack.org/wiki/StarlingX/Docs_and_Infra] if you are interested in translation." Also add (Layered Build) to the 	title line. OK to leave guide where it is in the index file.
	o TSN in Kata containers - Yi Wang author - Merged. Mary to do clerical edits.
	o Rook migration - Martin Chen author - needs author updates. Mary will do clerical edits after merge. 
	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 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.
	o What do other OpenStack projects do? 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)
	o 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 tentative 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.]
	o 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.
	o Going forward, if you update master 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 and we need to ask for help. 
	o AR Mary, reach out to Ildiko, we need help with 2 things: 1) search bar and 2) versioning/branch the docs for better usability. Need web developer help to implement these changes. Suggestions?





More information about the Starlingx-discuss mailing list