2022-01-10 - Plenary: Consistent Documentation Standards

Owned by Scot Steele
Last updated: Jan 10, 2022 by Beth Cohen
2 min read



Topic Leader(s)

  • @Beth Cohen

  • @Scot Steele

Topic Overview

60M

The organization could benefit from a possible revamp/alignment of documentation standards. Open to any community that would like to participate, suggesting Anuket/ODL/ONAP particicpate.

Slides & Recording

YouTube

Please indicate your session type in the blank space below and then remove this Info field.

  • Demo / Informational (non-interactive)

    • You may be asked to pre-record this session which will be made available on-demand.

  • Live Interactive Session

LFN Staff may elect to publish some videos to YouTube.  Please indicate here if you do not want your session to be published to YouTube.

LFN-2022-Doc Stan.pptx

Agenda

Awesome presentation

  • Do we have standard documentation across LFN project?  No!

  • How can we do create a standard for documentation across the projects?

Minutes

  • Introduction by @Heather Kirkseyabout how important documentation is in terms of the success of the LFN projects.  

  • Additional types of docs including: Contributor Guide with some of these are we replicating what the community or the vendors provide.  User guide and developer guides are different in ODL @Pankaj.Goyal Some of this documentation would be project specific. For example, in Anuket some of these are provided by outside of the project as Anuket is constraining the config etc. but not providing new software.  

  • Put together a list of project docs.  Not all projects are going to need all the docs.  Most of them are on the slides.  @louie.long Integration & Test Guide (5G Super Blueprint).  If its an update with additional features, would you want to show you how to use it ,how different it is and how it works?


  • @Cédric Olliviernotes that we need to be careful about where we store/host the docs.  The WIki should not be considered a permanent repository.  Need to think about where the docs are stored to be accessible to the users.

  • Further to @Thomas Kulik, complex systems such as ONAP require minimum (or a core) set of required components, their interactions, etc.
    You can address the issue by requiring the list of mandatory documents for all major independent components of the system a la OpenStack projects (Neutron, Nova, etc.).  there was a huge work to migrate old wiki "docs" to official RST doc in ODL

  • @Cédric Ollivier It's more or less the case in LFN. I would consider the main issue is to maintain all these docs. without misleading a lot our end users with doc in tree vs wiki, project document vs release documents, etc.

  • How about setting up a standard based on the role of the users of the project outputs – Admin, developer, end user, contributor, etc.

  • Force documentation to be part of the project deliverable.  A release or new feature is NOT accepted without the documentation be part of the project.  Make it easier to fold in docs into the release.  Need a standard set of "Tool" (Templates, structure)  @Cédric Ollivier Ideally in opensource, you vote -1 if the new feature is not documented enough - See OpenStack

Action Items