Istanbul Documentation: Lessons Learned

Architecture description

Observation

Responsibilities and delivery process unclear. Stakeholders and tasks are not covered by the release process. Updates for the architecture description must be manually inquired from the Architecture Subcommittee and LFN Marketing and hence are provided late in the release process.

Relevant files:

• ONAP Overview [GIT] [RTD]

• ONAP Architecture [GIT] [RTD]

Suggestion for improvement

• doc PTL Thomas Kulik and RelMgr David McBride to clarify responsibilities and tasks with all stakeholders.
• RelMgr David McBride to add tasks and due-dates for all stakeholders and related tasks to the release process. Also implement effective monitoring to ensure quality and compliance with time shedules.

Marketing/Composite release note

Observation

Responsibilities and delivery process unclear. Stakeholders and tasks are not covered by the release process.

Who is in the lead to use the content provided in the 'Release Key Updates' to create the Marketing/Composite Release Note?

Content in 'Release Key Updates' (e.g. for the 'istanbul' release) is partly not provided by the projects/subcommittees. Partly it must be rephrased to be used in the Marketing/Composite Release Note.

Suggestion for improvement

• doc PTL Thomas Kulik and RelMgr David McBride to clarify responsibilities and tasks with all stakeholders.
• RelMgr David McBride to add tasks and due-dates for all stakeholders and related tasks to the release process. Also implement effective monitoring to ensure quality and compliance with time shedules.

Process description for ONAP project teams to create project documentation

Observation

For the ONAP project teams there is no clear set of instructions to create the release specific project documentation for an ONAP release.

Suggestion for improvement

• doc PTL Thomas Kulik and team to describe the process from an ONAP project point of view and to provide this set of instructions in the ONAP Dev Wiki. See P02: Create documentation for an ONAP release (ONAP project teams)

Sphinx configuration files for ONAP project teams

Observation

There is no guidance for ONAP project teams how to configure sphinx and related functions properly to ensure a working documentation build process.

Previous config not robust for changes of LFIT / required libraries (lfdocs-conf)

Related files (examples taken from the vfc/nfvo/lcm repository):

• <project>/docs/tox.ini [master] ['newbranch']

• <project>/docs/conf.py [master] ['newbranch']

• <project>/docs/requirements-docs.txt [master] ['newbranch'] (no change in file)


• <project>/.readthedocs.yaml [master] ['newbranch'] (no change in file)

Suggestion for improvement

• doc PTL Thomas Kulik and team to provide a set of example configuration files which can be extended by the project teams
• doc PTL Thomas Kulik and team to check existing project configuration and to notify projects to use the examples in case there is a difference (configuration extentions by the projects are allowed and welcome!)

Documentation comes late in the release process

Observation

Documentation comes late in the release process and the 'doc' project team has only limited resources to handle all the activity close to the release date

Suggestion for improvement

• doc PTL Thomas Kulik and team together with RelMgr David McBride to improve the release process so that the load of the doc team is distributed better in the release process.

Gating process for changes in LFIT libraries

Observation

Changes to the lfdocs-conf library where released without an gating process. Projects (e.g. ONAP) which are relying on this library were not involved. The existing sphinx configuration for building ONAP documentation was not robust/resilient enough to avoid major impacts by this change.

Suggestion for improvement

• Cédric Ollivier together with doc PTL Thomas Kulik and team to improve the sphinx configuration and make it more resilient
• LFIT Jessica Gonzalez to implement a proper gating process

Management of (sub)project maintainer in ReadTheDocs

Observation

Maintainers of (sub)projects in ReadTheDocs must be managed manually. Depending on who is creating the (sub)project (e.g. LFIT, doc team), relevant maintainers are missing. 

Suggestion for improvement

• global jjb; readthedocs / new (sub)project / add doc contributer as maintainer automatically; to be detailed by Cédric Ollivier 

Maintenance state for mandatory ONAP components (projects/repositories)

Observation

Currently, an ONAP release consists also of components (projects/repositories) which are no longer maintained (but required for a good reason). This makes the management of security, the release and also documentation difficult and can be seen as a security risk. An ONAP release must not rely on unmaintained components.

Suggestion for improvement

• TSC cl664y@att.com and RelMgr David McBride to ensure that a) unmaintained + not mandatory components are removed from the release and b) unmaintained + mandatory components are (at least) under "basic" maintenance (security & docs are up to date, but no feature updates)

Merge conflicts while maintaining the 'doc' repository

Observation

Especially in the last phase of the release we ('doc' team) experience multiple merge conflicts while maintaining the 'doc' repository.

Suggestion for improvement

• open - to be described