2021-09-02 Doc project meeting

AGENDA FOR TODAY

Doc Procedures

Procedure "P01: Create documentation for an ONAP main release" is currently under development by @Thomas Kulik

TASKS:

• Team: Please review and give feedback what can be improved

ArchNav Internship / SVG ArchMap

• Internship of @Nicholas Karimi has come to an end

• ArchNav will be maintained by @Chaker Al-Hakim 

Architecture Documentation in RTD

There is the need to move finalized ONAP architecture documentation from DevWiki to RTD. Especially the following section are from interest (examples from the Istanbul release):

• Architecture Map

• Component Descriptions (incl. sub-pages)

Evaluation started; Confluence has now a new functionality to export a page to markdown format; lets see if/how this can help (attachements unfortunately are not included)

TASKS:

• @Andrea Visnyeito support the process of transferring the information from DevWiki to RTD

• @Thomas Kulikto support here and check how this process can be automated. Especially the embedded draw.io diagrams (special confluence macro) may cause problems if we use confluence2md to export pages). Shedule a meeting with @Chaker Al-Hakimand team.

• @Chaker Al-Hakimand team to support the transfer.

• @Chaker Al-Hakim, @Thomas Kulikand teams to create a process to transfer information to RTD also for upcoming releases.

• DOC team will migrate 3 to 5 pages / the remaining pages are in the responsibility of the ARC team

Backlog Clean/Sort/Reorder

We will do it in jira!

TASKS:

@Thomas Kulikhas prepare a deduplicated and sorted list of open tasks. Next step is to go through the list and remove outdated/unwanted entries.

Issue with RTD TOC

TASKS:

@Andrea Visnyei / @Thomas Kulik check RTD TOC for https://docs.onap.org/en/latest/guides/onap-developer/how-to-use-docs/templates.html

Doc Templates

TASKS:

@Andrea Visnyei and @Andreas Geißler to check current component template and improve if needed

API Documentation

TASKS:

@Kenny Paul , @Eric Debeau Session with @Andy Mayer  needed to clarify how we continue on the API documentation (swagger). The API docs are part of the ARC docs. See also in DevWiki.

@Nicholas Karimi join Kenny in the discussion with @Andy Mayer .

See also in Swagger in RTD

@Eric Debeau will discuss with @Kenny Paul and @Andy Mayer 

Doc Guideline

TASKS:

Ask users to add always the original file of grafics to the repo (plus the bitmap version of course which is used in wiki/RTD)

Istanbul Release

TASKS:

#doc team: Review Istanbul release notes and project content

@Eric Debeau and @Andreas Geißler will start next week to review and document the results in Istanbul Documentation

Please note down also problems with the process and possible improvements. They will be used in P01: Create documentation for an ONAP release (doc project team)

Honolulu Maintenance Release

@Andreas Geißler will start to create release notes based on Jira tickets

it is also important to document the process (later on used in a procedure)

Usage of Confluence "Tasks" in Meeting Notes

Please do not use "Tasks" in this meeting note. The meeting note is planned to be copied for the next meeting. Unfortunately all "Tasks" are also copied and a NEW INSTANCE of this tasks is created. This leads to multiple duplicated of a single tasks. 
Suggestion: Create a single "Task Page" and embed only a reference in this meeting note. Please always check upfront if this task can/must be added to the DOC JIRA issues instead. 

Other

TASKS:

• @Kenny Paulto check if we can get support (eg. additional internship) to extend the capabilities of the "confluence2md" tool

• @Kenny Paulto discuss with @Jessica Gonzalezif and how we can avoid multiple duplicated tasks in the DevWiki

• @Thomas Kulikto add a chapter  to RTD that holds information about UseCases and supporting ONAP releases (like we have it in the Architecture Navigator)

Vacations & Upcoming Meetings

• @Thomas Kulik Vacation from 03.09.2021 until 17.09.2021

• @Andreas Geißler Vacation from 13.09.2021 until 24.09.2021 

• next #doc meeting scheduled for 09.09.2021 and lead by @Eric Debeau 

NOT DONE DUE TO TIME CONSTRAINTS

Open gerrit issues

• We went through the open gerrit issues for Honolulu (Maintenance)  / Istanbul release

Open jira tickets

• We went through the open Jira issues for Honolulu (Maintenance)  / Istanbul release

TASKS:

@Thomas Kulik : Propose that every project should use tox.ini (incl. link check)? Create a new Epic for this? conf.py must be updated as well!

Sprints

• Should we structure our (doc) work in sprints?

TASKS:

@Thomas Kulik : Ask for DT-internal help to set up this structure. @Eric Debeauand @Andreas Geißlerwill help as well.

Guide Doc Dev System

• Released and updated; @Timo Perala volunteers for review.

OPTIONAL (IF TIME ALLOWS)

All

Collection of topics not started

TASKS:

• Dedicated repo for every subcommittee (that creates and maintains formal ONAP documentation)? To be discussed.

• Fix ReadTheDocs starting page to the last official release (and not 'latest')

• Copyright notice an RTD still shows the wrong year.

Objectives for upcoming releases

Jira ticket walkthrough,

The team will investigate further with the OOM team on how to enable a non-voting job for warnings. 

TASKS:

Check why closes ticket show up even when the filter is set to "Open" or "In progress"

Honolulu Maintenance Release 

• open

Architecture documentation 

TASKS:

• 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.

• Discuss with architecture team, how the following docs can be transfered to RTD:
  see:

Documenting ONAP Architecture (New)

Istanbul-R9 Architecture General Description

Istanbul-R9 ONAP Architecture Component Description

Link management in RTD @Eric Debeau

Many links are managed in RTD

• local links within a repo

• inter-project links using inter-links from sphinx

• links to code repo

• external links to web sites

There is a problem when a documentation linkes to a repo => the branc is not indicated. As result, the link points to the latest release

Propostion to provide guidelines to be then presented for PTL

Many links are broken => need to include a test in JJB and provide information about broken links

Feedback has been given, positive output. Next step, bring to PTL 

Sill required from the project to test

Create project docs manually with gerrit in case a project has branched but not changed any file in the new branch afterwads

@Andreas Geißler showed a solution to create project docs manually within gerrit in case a project has branched but not changed any doc file in the new branch afterwards. There are extended right in gerrit needed ("