2020-10-08 Doc project meeting

Documentation hackathon for Guilin - dates needed

Make sure you attend the second doc hackathon scheduled during the event next week. We will focus on reviews 

see:  DOC-672 - Getting issue details... STATUS  Copy of Guilin Documentation (working version for reviews) Andreas Geißler

see:  DOC-671 - Getting issue details... STATUS  Andreas Geißler

see:  DOC-673 - Getting issue details... STATUS  Andreas Geißler

Discussion on session proposed by Thomas Kulik

Event shedule: https://teamup.com/ksgw6qzqcmg9zbzsfq?view=MD&date=2020-10-13&filterby=8227782,8310614,8310707&viewstate=%7B%22number%22%3A3%7D

****** PROPOSAL - TO BE DISCUSSED ******

Impact of the current ONAP release- and branching strategy on documentation. Discussion of the problems and possible solutions.

Problem Statement:

The Doc team has the responsibility to create an “umbrella document” that is the entry point for ONAP documentation (example) .
This file provides all the links to release specific documentation for functional as well for non-functional components.

Currently, a full list of (sub)components that are part of an ONAP release is not available.

Currently, not all projects create a branch. This leads to the problem, that within a release-specific ONAP documentation (example) some links for the (sub)component documentation are pointing to the "release branch" and some are pointing to "latest".

Proposals:

• Create and maintain a full list of (sub)components and its provided documents that are part of an ONAP release. (see ongoing work at Copy of Guilin Documentation (working version for reviews) )
  
  • In this list, all release relevant functional and non-functional components must be included (e.g. Architecture, Security, Modelling, VNF Requirements, Use Cases).
  • This list should be used in each release for reference in the Release Lifecycle process.
• Release Process improvements:
  • All (sub)components that are part of a release must create a release branch (which then can be referenced in the release documentation with a release specific link). 
  • The release note for the (sub)project must be updated accordingly (e.g. release name, version number, changes, known issues).
  • All documentation content must be validated (and changed if required) to ensure that it fits to the release. A note about this validation (or update) must be found in the (sub)project release note.
  • The availability of the described information and the execution of described tasks must be ensured by corresponding milestones of the release process.
• Review and update of the ONAP release process accordingly (Release Lifecycle)

Required Participants:

• Release Manager (David McBride),
• OOM Team Representative (?TPL),
• Doc TPL (Sofia Wallin)
• Doc Team (Andreas Geissler, Thomas Kulik, Eric Debeau, and more)
• TSC Lead (Catherine LeFevre),
• LF Release Engineering / Tech Support (Jessica Wagantall, Aric Gardner, …)

Duration:

1 hour

Comments from Sofia Wallin

The heading of the session and the "problem statement" doesn't align to me. Maybe calling it something like "Release requirements for documentation". Some of these proposals are already implemented (such as corresponding milestones) but could probably be improved. Someone need to make sure that we reach out to the people that are asked to participate. Also, I would avoid mentioning branching strategy since this is not a problem to solve for the doc project 

Documentation guide 

Thomas Kulik Jakob Krieg

Thomas Kulik : Documentation Developer Guide (https://docs.onap.org/en/latest/guides/onap-developer/how-to-use-docs/index.html) extention planned for Beginners and restructure extisting Guide ( DOC-602 - Getting issue details... STATUS )

Jakob Krieg : Created ticked about Testing instructions  DOC-651 - Getting issue details... STATUS

MS2 to start next week.

Sriram gives an update in TSC meeting following this meeting

******************************************************

MS1 close to finished. 

MS2 in review for prioritization (work starting in next 2 weeks) 

Status update page: Documentation improvements for end to end usage of ONAP

An update to the TSC will be done within a couple of weeks.

Local environment to write RST files Eric Debeau

Eric Debeau presented local documentation testing. We will document a basic for version for local RST rendering. Further extensions will be available if needed/wanted (such as spell checker + Linter) but this requires a more extensive set of tools. To be presented in the PTL call for feedback.

 ************************************************************************************

Local environment to write RST files and detect

Visual Studio Code IDE + Extensions (Spell Checker + Linter)

Automatic preview aligned with ONAP documentation schemes