2021-09-02 Doc project meeting (planned)

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

• ONAP Web Based Architecture Navigation Solution
• Architecture Navigator page @doc project: Architecture Navigator (ArchNav)
• contribution of Nicholas Karimi currently scheduled until the end of July 2021
• Ultimate goal is to have a good structure to get information easily findable.
• ArchNav is used also in the process of architecure reviews and holds additional information about ONAP uses cases
• POC/Proposal for a architecture map natively designed in Inkscape has started. The SVG format has capabilities to add links, additional text and mouse-over effects to elements. Presentation in the ARC subcommittee meeting as well in the TSC are planned.
• The idea is that this SVG-map is handed over to architecture team to be maintained in the future. Also it is planned to use it in RTD for a user-friendly entry-point for navigation.

TASKS:

• First: Identify Maintenance Model (who is able to maintain it in production / for all the upcoming releases of ONAP)
• Identify the use cases currently applied to ArchNav and use cases for the Doc team's needs
• Look at the potential use of LF Landscape 
• Look at the potential use of Inkscape for a clickable graphic (Eric Debeau has done a PoC of the functionality)

RESULT:

• Nicholas: To help to maintain the SVG map in the next step
• ArchNav results to be announced in the TSC
• ArchNav to be turned into an OS project; discussion with Chaker Al-Hakim ongoing.

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.

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.

TASKS:

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

TASKS:

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

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

Postponed until Eric Debeauis back from vacation.

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)

• 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 sheduled for 09.09.2021 if someone volunteers to lead the meeting and to take the notes

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

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

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

• Released and updated; Timo Perala volunteers for review.

Jira ticket walkthrough,

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

TASKS:

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

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 ("