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

Compare with Current View Page History

« Previous Version 32 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.doc

Project description:

  • Create and maintain documentation targeted to ONAP user audiences and the tasks they perform.   Illustrative examples to be defined in each release:
    • 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;

  • Establish and maintain a tool chain that supports the integration of documentation source material from all ONAP projects and committees and builds documentation artifacts for each release.
  • Benefits include:
    • documentation is an integral part of the design and development of an ONAP release. 
      • the software architecture, design models, etc. influence the language used to document the end to end platform to a user audience
      • creating the end to end view for a user audience drives consistency, conceptual integrity, and clarity of design.
      • documentation can be tested during development and may reduce the effort to write test cases and installation instruction early in a release cycle.
    • documentation source maintenance is closely aligned with a contributor whose work impacts the documentation, automatically updated as part of the CI/CD process, and will be in sync with the software in a release.
    • ONAP, user audiences will quickly understand how to use ONAP and perform required tasks

Scope:

  • Describe the functionality to be provided by the project. 
    • Curator/Editor Functionality provided by committers and contributors to documentation project for each ONAP release.
      • Identify the documentation required for a release based on an end to end view of targeted user audiences, tasks requirements, use cases, input from ONAP committees (architecture, marketing, etc) and approved projects. 
      • Review project, release plan, and committee artifacts early in a release to identify opportunities to align on clear end to end platform terminology and to test early drafts of documentation.
      • Create/Update a top level index for all documentation in an ONAP release (org.onap.doc repository).
      • Create/Update sub-repositories below org.onap.doc/sources for projects and committees that provide documentation source material.  Committer ACLs on sub-repositories may supplement or override the inherited org.onap.doc committer ACL to align control with other projects providing the source material.
    • Content Creation Functionality - provided by contributors to this project or other sources
      • Write documentation that references platform technical documentation and presents in a form tailored to a particular user audience and task.
    • CI/CD Functionality provided automatically by tools created and/or configured by doc project contributors and committers
      • Gerrit, Jenkins job builder configured to generate a new published documentation any time the top level or lower in the doc repository hierarchy change.   A successful build will trigger an update at Readthedocs.

  • Specify any interface/API specifications proposed
    • Sphinx and ReStructuredText will be used for index structure and source document contents that are built from gerrit repositories and updated at Readthedocs.
    • TBD other tools for auto generated or documentation embedded in source code (Swagger, Javadocs, etc.)


  • 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 as describe above
      • Release 1 documentation
      • Migration of seed documentation currently in the wiki or gerrit that is being maintained by approved projects
    • 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
    • Documentation specified in the Release Planning Template
    • Early release information from committees (architecture, use case, marketing, etc.) and projects to determine user audiences,  task requirements, and end to end platform capabilities.
    • Early release integration project plans to align documentation and test plans.
  • 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?

Resources:

Other Information:

Key Project Facts

Project Name:

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

Repo names:

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



Lifecycle State: proposal
Primary Contact:
Project Lead:
mailing list tag [doc]
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