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

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 Catherine Lefevre , 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.
  

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)

Agreed actions

• as suggested; initial version in progress

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 Cedric Ollivier  and team to provide a set of example configuration files which can be extended by the project teams
• doc PTL Thomas Kulik Cedric Ollivier  and team to check existing project configuration and to notify projects to use the examples in case there is a difference (configuration extensions by the projects are allowed and welcome!)

Agreed actions

• as suggested; initial version in progress
  

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.

Agreed actions

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

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

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

Agreed actions

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

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 Cedric Ollivier 

Agreed actions

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

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 Catherine Lefevre 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)

Agreed actions

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

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

• open - to be described

Agreed actions

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