Versions Compared

Old Version 29

changes.mady.by.user Rich Bennett

Saved on

compared with

New Version Current

changes.mady.by.user Thomas Kulik

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Proposal Date:

  • 5/11/17

Project Name:

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

Project

...

Description:

...

  • Create and maintain documentation targeted to ONAP user audiences and the tasks they perform.   For exampleIllustrative examples below, specific list to be defined or each ONAP 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;
    • 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 committees 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
      • document the end to end platform to a user audience
      or vice versa
      • creating the end to
      audiences and platform drive
      • end view for a user audience drives consistency, conceptual integrity, and clarity of design.
      • documentation
      is efficiently maintained with the software, created
      • 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, release documentation is automatically updated 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 ONAP user audiences will quickly understand how to do use ONAP and perform required tasks

Scope:

  • Describe the functionality to be provided by the project . 
    • Curator/Editor Functionality Curate/Edit/Organize Documentation - provided by committers and contributors to this documentation project for each ONAP release .including
      • Identify Identifying 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.Create  
      • Reviewing projects, release plans, and committee artifacts early in a release to align on end to end platform terminology and where draft documentation is provided in the release plan
      • Creating/Maintaining a top level index for all documentation required for in an ONAP release in the (org.onap.docs doc repository).
      • Identify sources and create Creating/Maintaining sub-repositories below org.onap.docs doc/sources for projects and committees that provide documentation source material.  Committer ACLs on sub-repository repositories may supplement or override the inherited org.onap.docs ACLs doc committer ACL to align control of the sub-repository with other 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.
      • .
      • Providing consistent terminology and style guides for contributors.
    • Write Documentation - provided by contributors to this project or other sources
      • Create documentation source material that references other project provided source material and adds information tailored to a particular user audience and task.
    • Documentation CI/CD Tool Chain -  committers and contributors to the doc project create and/or configure tools that automatically generate release documentation from all sources
      • Gerrit, Jenkins job builder will be configured for each release to generate a new to build documentation any time the a top level or lower in the docs 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 pattern / relationship we describe above with other projects and sources of material that are integrated in the documentation, Release 1 documentation.
      • Implement Linux Foundation best practice CI/CD tool chain
      • ONAP 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.
    Image Removed
  • Dependencies on all projects, committees that provide source material for documentation.
    • Target use cases drive the user audience and task requirements for a releaseCreates an end to end platform and user audience view of documentation, organizes documentation source material from all projects and sources, and provides a CI/CD documentation tool chain for published documentation.
    Image Added
  • 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 Linux Foundation best practices for a documentation tool chain based on experience with 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:

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

Lifecycle State: proposal
Primary Contact: Rich Bennett
Project Lead: Greg Glover
mailing list tag [docsdoc]
Committers:

Rich Bennett, rb2745@att.com, AT&T
Nicholas Hu, jh245g@att.com, AT&T
Timo Perala, timo.perala@nokia.com, Nokia
Greg Glover, gg2147@att.com, AT&T
Kevin Scaggs, ks0567@att.com, AT&T
Steven Wright, sw3588@att.com, AT&T
James Yang, james.yangliu@huawei.com, Huawei
Shasha Guo, guoshasha@chinamobile.com, China Mobile
Ying Li, liyingyjy@chinamobile.com, China Mobile
Lili Kong, konglili@chinamobile.com, China Mobile
Andrea Anderson, andrea.anderson@amdocs.com, Amdocs
Matthew Harffy, matthew.harffy@amdocs.com, Amdocs



Contributors:

Andrei Kojukhov, andreik@amdocs.com, Amdocs
John Buja, john.buja@amdocs.com, Amdocs
Bernard Frazer, bernard.frazer@amdocs.com, Amdocs
Shawn Loewen, shawn.loewen@amdocs.com, Amdocs





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