Istanbul Documentation: Lessons Learned

Owned by Thomas Kulik
Last updated: Mar 31, 2022
5 min read

NOTE: This document complements: Increased transparency on software modules included in an ONAP release



TABLE OF CONTENTS



01

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:

Suggestion for improvement

doc PTL @Thomas Kulik and RelMgr @David McBride to clarify responsibilities and tasks with all stakeholders @Chaker Al-Hakim @Kenny Paul @Byung-Woo Jun
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.

Agreed actions

Type your task here, using "@" to assign to a user and "//" to select a due date

02

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 Composite Release Note.

Suggestion for improvement

TSC @cl664y@att.com , RelMgr @David McBride and doc PTL @Thomas Kulik 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 schedules.

Agreed actions

Marketing is not responsible to provide the content for the Composite Release Notes. TSC Chair and doc team will create it from the 'Release Key Updates' page.
@David McBride It must be ensured that the content from this table is delivered by the projects in a suitable format which needs no additional revision.

03

Branching of repositories

Observation

See Increased transparency on software modules included in an ONAP release

Suggestion for improvement

Agreed actions

  •  

    Type your task here, using "@" to assign to a user and "//" to select a due date

04

Management of ONAP projects/software modules participating in a release

Observation

See Increased transparency on software modules included in an ONAP release

Suggestion for improvement

Agreed actions

05

Process description for 'doc' project team to create ONAP documentation

Observation

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

Suggestion for improvement

Agreed actions

06

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

Agreed actions

07

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

Suggestion for improvement

Agreed actions

08

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

Agreed actions

09

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

Agreed actions

10

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

Agreed actions

11

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

Agreed actions

12

Merge conflicts while maintaining the 'doc' repository

Observation

The 'doc' project team and also people from other teams are proposing patches to documents residing in the 'doc' repo. Especially in the last phase of the release we ('doc' project team) experience multiple merge conflicts while maintaining the 'doc' repository.

Suggestion for improvement

Agreed actions