2021-01-14 Doc project meeting

• Documentation process 
  • minimum scope for participating projects (planning, reviews, branching etc) 
• Getting started with your documentation
  • Suggestion to schedule a session for the upcoming virtual event
• Cleaning up outdated content
  • Continuously clean up out dated content from RTD. How to do this in a structured way?
• Enable a voting job -1 for warnings (te be excluded long line) 
• API Documentation handling

Sofia Wallin to create a release planning page for Honolulu. 

Sofia Wallin to invite Jessica to the next meeting for discussion around enabling voting jobs for warnings.

Follow up with the TSC and/or Catherine and David. Eric says that progress has been made but work still needed. 

Invite David McBrideto discuss how to track this best. To create Jira ticket as "relman" or doc project?

Ensure that documentation is added as a requirement for the release. Bring to the TSC 17/12 (Eric Debeauor Andreas Geissler)

Targeted audience new comers. To propose having a hands-on hacking session. How to get started and write documentation. Owner Eric Debeau

Targeted audience All. Documentation process (planning, reviews, branching etc). Owner Sofia Wallin

Targeted audience All. Tool introduction. generating and validate diagrams from Tosca. Owner Eric Debeau

Targeted audience All. Improvements made by the docs team. see https://wiki.lfnetworking.org/display/LN/2021+February+Developer+Topic+Proposals#id-2021FebruaryDeveloperTopicProposals-ONAPDocumentationImprovementsandPlans Owner Andreas Geissler

For future collaboration and facilitation we will ask for a time slot in the arch subcommittee meeting to inform and educate how to work with docs.

https://gerrit.onap.org/r/c/doc/+/115497

• Documentation build issues 

Follow up with Jessica. Any news from RTD on feature adding. 

When the build jobs are failing on RTD can we get feedback in Jenkins?

• Branching strategy Eric Debeau and Sofia Wallin (all doc project)

• Documentation tracking Thomas Kulik

David McBride will join to discuss this further. 

• Intersphinx mapping Jessica Wagantall

Problem statement:

The conf.py with the intersphinx mapping has different settings/configurations. Some projects refer to the latest branch and some stable/Frankfurt. 

After migrating we did see that some projects refers to latest even when choosing Frankfurt on RTD. Could this be because of the configuration or is the configuration based on whether the projects have created a release branch or not?

Sofia Wallin  From what I learned from Aric, we do not need to change the branch in each repo whenever a project creates their branch. The branch= foo in the conf.py only applies to the default rtd theme, it doesn't do anything for the theme ONAP is using. 

All projects need to have build the stable branch before we can switch the main doc to be the next release branch. 

We submitted and cherry picked the final patches. Sent an email to the team to get the tutorials published on RTD according to the decision taken in December.

These 3 should be moved to the ONAP user guide section as an rst file,

https://wiki.onap.org/display/DW/vFWCL+Design+Tutorial

https://wiki.onap.org/display/DW/ONAP+Service+Design+%28vFW%29+Tutorial

https://wiki.onap.org/display/DW/ONAP+Service+Deployment+%28vFW%29+Tutorial

But the AWS specific tutorial will remain on the wiki,

https://wiki.onap.org/display/DW/Instructions+for+K8S+cluster+setup+on+AWS

• 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

Sofia Wallin to create a wiki page and send to Eric

DOC Local environment to write and test RST files

Eric requests the team to try the instruction before bringing it to the community.

• Link management in RTD Eric Debeau