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

Camp, MaryX maryx.camp at intel.com
Wed Sep 16 21:35:31 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    << Starting 21Sep20, STX Zoom meetings will change to add a passcode. Check here for new link/info.
  [2]   Tracking Etherpad: https://etherpad.openstack.org/p/stx-documentation

thanks,
Mary Camp
==========
2020-09-16

All -- reviews merged since last meeting:  0
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 being worked: https://review.opendev.org/#/q/status:open+project:starlingx/docs+branch:master+topic:ceph-cluster-editorial
   Mary question: about these changes against "R5" install guides... when merged, we don't want to cherry-pick these changes into the R4 branch, right?
   Rook is NOT officially in r4.0 but code will merge quickly afterwards. Orig review 723291 has link to story https://storyboard.openstack.org/#!/story/2005527

All -- Opens

Upstreaming WR docs status
+   Need to submit batches larger than expected due to links within docs. Tox fails due to missing links, not just a warning. Probably will have to submit 1 entire book at a time. Plan is to comment out the links to other docs. Ron and team will come up with suggested comment string to use for cleanup later.
+   Need to merge the "substitutions" review so that further testing can happen. Mary gave +2 during meeting. After meeting, Bruce also +2, then +1 workflow. This is now merged.
+   Question about mini-TOC at the beginning of guides. Relevant in STX docs because they are monolithic guides and some are very long. Different for WR because the DITA topics are generally small by design. We agreed that adding a mini-TOC is a judgement call during the conversion process. Preliminary guideline is: if the RST file has more than one level1 heading (not title) and the 2nd level1 heading is >75 lines down the page, then add mini-TOC .
   Here is example of the lines to add:
   .. contents::
      :local:
      :depth: 1
+   Acronyms - we discussed the best method to implement, pre-conversion vs post-processing, seems a toss-up. We agreed to not do anything special for the first document and evaluate afterwards. We could use the substitutions file to fix after.
+   AR Mary to send Ron/Juanita my cheatsheet with info about Sublime text editor and the plugins that I use (line length, blank spaces, etc).

Display multiple versions of STX docs - No updates this week.

Release 3.0.1:  Mary will attend release meeting this week and ask about Release Notes. Likely to be a simple format like R2.01 RN [https://docs.starlingx.io/releasenotes/r2_0_1_release.html]

Housekeeping note:  Starting next week, Zoom meetings will change to add a passcode.
New link/passcode will be available here after the weekend: https://wiki.openstack.org/wiki/Starlingx/Meetings#12:30pm_Pacific_-_Docs_Team_Call

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.starlingx.io/pipermail/starlingx-discuss/attachments/20200916/f2797bb2/attachment.html>


More information about the Starlingx-discuss mailing list