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

Compare with Current View Page History

« Previous Version 30 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.
  • Benefits include:
    • documentation is an integral part of the design and development of an ONAP release thus the software architecture, design models, etc. influence the language used to describe end to end platform to a user audience or vice versa the end to audiences and platform drive clarity of design.
    • 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, conversion of seed documentation that will be maintained.
    • 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