You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 28 Next »

DRAFT for Review - Updated to Address TSC Comments and Align with LF documentation tooling best practices

Project Name:

  • Proposed name for the project: Documentation
  • Proposed name for the repository: org.onap.docs

Project description:.

  • Create and maintain documentation targeted to ONAP user audiences and the tasks they perform.   For example:
    • a platform developer pulling, building, running, hacking and pushing source code ;
    • an administrator installing, configuring, and monitoring an ONAP instance;
    • a designer or tester creating, validating, and delivering service models;
    • others as required for release plans or ONAP committees
  • Establish and maintain a tool chain that supports the integration of documentation source material from all ONAP projects and builds documentation artifacts for each release.
  • Establish documentation source material and final documentation dependencies in the release plan, end to end tests, and CI/CD to insure documents are available when needed in a release cycle and remain current with changes made in other software projects.
  • Enable technical writer (contributors) for each release to create and integrate additional content based on overall release requirements.
  • Benefits include:
    • documentation is an integral part of the design and development of an ONAP release thus
    • documentation is efficiently maintained with the software, created as part of the CI/CD process, and will be in sync with the software in a release.
    • in a released version of ONAP, users quickly understand how to do required tasks

Scope:

  • Describe the functionality to be provided by the project. 
    • Curator/Editor Functionality provided by committers and contributors to this project for each ONAP release.
      • Identify the documentation required for a release based on targeted user audiences, tasks requirements, use cases, input from ONAP committees (architecture, marketing, etc) and projects.
      • Create a top level index for all documentation required for an ONAP release in the org.onap.docs repository.
      • Identify sources and create sub-repositories below org.onap.docs for projects and committees that provide documentation source material.  Committer ACLs on sub-repository may supplement or override the inherited org.onap.docs ACLs to align control with projects providing the source material.
      • Review project, planning, integration, and committee artifacts or source material early in a releases looking for opportunities to align on clear end to end terminology and to test early drafts of documentation.
    • CI/CD Functionality provided by the tools created and/or configured by this project are triggered by a change in a source repository that the documentation depends on.
      • Gerrit, Jenkins job builder will be configured for each release to generate a new documentation any time the top level or lower in the docs repository hierarchy change.   A successful build will trigger an update at Readthedocs.

  • Specify any interface/API specifications proposed


  • Identify what is in or out of scope. During the development phase, it helps reduce discussion.
    • In scope - Best practice tool chain and CI/CD pattern / relationship we describe above with other projects and sources of material that are integrated in the documentation, Release 1 documentation.
    • Out of scope -
      • Training is not part of this project
      • Multiple Language Translations
      • VNF Requirements is a separate project and representative example of the pattern we describe, references to these have been removed from this proposal.

Architecture Alignment:

  • How does this project fit into the rest of the ONAP Architecture?  
    A parallel thread to create documentation artifacts with dependencies on the capabilities, configuration, and interfaces provided by software projects as illustrated below.

    • Dependencies on all projects, committees that provide source material for documentation.
    • Target use cases drive the user audience and task requirements for a release.
  • How does this align with external standards/specifications?
    • Project will use best practices for a documentation tool chain based on open daylight and opnfv.
  • Are there dependencies with other open source projects?
    • Evaluate the use of swagger.io for API documentation

Resources:

  • Primary Contact Person: Greg Glover,  Rich Bennett
  • Names, gerrit IDs, and company affiliations of the committers
  • Names and affiliations of any other contributors
    • TBD based on final requirements for Release 1
  • Project Roles (include RACI chart, if applicable)

Other Information:

Key Project Facts

Project Name:

  • JIRA project name: Documentation
  • JIRA project prefix: DOC

Repo names:

docs
docs/tools
docs/source/<repos created as required for source material from other projects, committees, etc.>



Lifecycle State: proposal
Primary Contact:
Project Lead:
mailing list tag [docs]
Committers:
rb2745@att.com
timo.perala@nokia.com
gg2147@att.com
ks0567@att.com
james.yangliu@huawei.com
konglili@chinamobile.com







*Link to TSC approval: 
Link to approval of additional submitters: 

  • No labels