2020-10-22 Doc project meeting

Owned by Sofia Wallin
Oct 22, 2020
4 min read

Attending

@Sofia Wallin @Thomas Kulik @Ramakrishna GP

Topics, Notes, Status and Follow-Up Tasks

Short meeting. 

@Thomas Kulik: Gave an update on the initiated conversation with @David McBride about evolving the tracking table. A meeting to be scheduled for further discussion.

@Ramakrishna GP: Work with MS2 is ongoing and on track. Question about the policy/engine repo that was removed, all work should be done on policy/parent. (Was requested by Pam earlier this year)

@Sofia Wallin: Waiting for response from @Jessica Gonzalez about the intersphinx mapping. To be continued next week. 



Topic

Notes / Status / Follow-up

Topic

Notes / Status / Follow-up

Upcoming milestones and release planning for docs

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

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

Status of the ONAP Component Document  

see: DOC-672: Update ONAP component document listClosed Copy of Guilin Documentation (working version for reviews) @Andreas Geißler

Status Notes: 

  • Name of the page should be updated

Discussion about "ONAP Active Project" page

see: DOC-671: ONAP Active Projects vs. ONAP ComponentsClosed @Andreas Geißler

Status Notes: 

  • Agreement: "ONAP Active Projects" will be removed

  • "ONAP components and functionalities" will be updated

Decision on "Tutorials" (see Jira) and Responsibility for "Architecture" RSTs in DOC repository

see: DOC-673: Remove outdated "Tutorials" pageClosed @Andreas Geißler

Status Notes: 

  • "Tutorials" will be removed

  • Agreement, that DOC pages "Architecture", "API Reference" and "ONAP Overview" should be maintained by the Architecture Subcommitee (with support from Eric)

Virtual event 

Discussion on session proposed by @Thomas Kulik

Event schedule: 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. (see Guilin Release Key Updates )

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 made 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 

Status Notes: 

  • Andreas will invite the required participants to discuss the issue in next weeks event



Link to the session recording and minutes:

https://wiki.lfnetworking.org/display/LN/2020-10-14+-+ONAP%3A+Impact+of+the+current+ONAP+release-+and+branching+strategy+on+documentation

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: Documentation guide refinementClosed)

@Jakob Krieg : Created ticked about Testing instructions DOC-651: Update Guide for Testing One ProjectClosed

Status Notes: No further updates

Update "Documentation improvements for end to end usage of ONAP"

@Aarna Networks



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.

Status Notes:

  • MS2 work starts, the Status page will be cept updated.

  • Reminder to check the gerrit reviewer lists to get the changes merged 

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

Status Notes: Eric has all information and will put it to Wiki, when he finds the proposed location