2021-10-07 Doc project meeting

Owned by Thomas Kulik
Last updated: Oct 07, 2021
3 min read

Attending

  @Thomas Kulik @Nicholas Karimi @Andrea Visnyei 



Topic

Notes / Status / Follow-up

Topic

Notes / Status / Follow-up



@Andrea Visnyei stated that there was no progress on the topic of migrating Wiki pages to RTD.

@Thomas Kulik gave a short info about the current state of the build problems.

All: Due to very low attendance and lack of topics we have decided to shorten the meeting.

AGENDA FOR TODAY



Current JJB/RTD Build Problems

@Cédric Ollivier gave an explanation of the pb (mainly lfdocs-conf)

ONAP does not leverage upper-constraints

see also https://gerrit.onap.org/r/c/dcaegen2/+/124578

TASKS:

LFIT to downgrade sphinx to 3.4

LFIT to downgrade setuptools to 57.4

LFIT to create gates to verify changes

all ONAP projects: reduce requirements.txt; add upper-contraints

?: find central place for upper-constraints.os.txt

?: maintain our own upper-constraints because ??

?: sync tox.ini ??



Help to fix docs for H maintenance release for the following projects:

Honolulu Maintenance Release

@Andreas Geißler

TASKS:

@Andreas Geißler will ask SO and CDS projects to finalize the Docker creation and documentation

it is also important to document the process (later on used in a procedure) => P02: Create documentation for an ONAP maintenance release (doc project team)

Istanbul Release

#doc team: Review Istanbul release notes and project content

@Eric Debeau and @Andreas Geißler reviewed and document the results in Istanbul Documentation

=> some comments from @Andreas Geißler 

Some projects to move on "Unmaintained" mode (ExternalAPI, VID)

TASKS:

@Eric Debeau Still clarification required for Architecture section (Architecture subcommittee)

@Eric Debeau  Modeling update to be checked

@Eric Debeau clarification on MSB status

@Eric Debeau  @Andreas Geißler Eric Update conf.py file



Doc Procedures

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

A dedicated procedure related for Maintenance Release: P02: Create documentation for an ONAP maintenance release (doc project team) has been created



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):

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)

Pending pach: https://gerrit.onap.org/r/c/doc/+/123946. @Eric Debeau did some comments

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

  • @Gergely Csatari did a patch for: https://gerrit.onap.org/r/c/doc/+/123946He will test the scripts on Components wiki page: 

    https://lf-onap.atlassian.net/wiki/display/DW/Istanbul-R9+ONAP+Architecture+Component+Description



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

@Andy Mayer presentation, Developing ONAP API Documentation

@Andy Mayer gave us a good introduction to API documentation

TASKS:

@Eric Debeau to check available API documentation in RTD and how to update with material proposed by @Andy Mayer 

doc team; next steps: (update) description how to include it in RTD; prepare sample config files; check if we need to create a procedure for this (like we have it for creating main/maintenance release documentation)

example RTD link:

https://docs.onap.org/projects/onap-ccsdk-oran/en/latest/offeredapis/pms-api.html

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)

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

  • @Andreas Geißler Vacation from 13.09.2021 until 24.09.2021 

  • next #doc meeting scheduled for 30.09.2021