Versions Compared

Old Version 12

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;
    • a VNF developer designing, testing, and certifying a VNF for use on ONAP
    • a Service Provider using VNF Requirements as prototype text for RFPs to acquire VNFs to run in an ONAP context
    • ... 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.
  • Establish a process to recognize source and final documentation dependencies in the release plan, end to end tests, and/or CI/CD to insure these deliverables are created early in a release cycle and remain current with changes made in other projects.
  • Identify technical writers for each release to create and integrate content based on overall release requirements.
  • Benefits include users quickly understand how to do required tasks, documentation is efficiently created and is 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, release documentation is 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 . 
    • Documentation artifacts for ONAP release that contain
      • original content created by the documentation project and
      • integrate source material from any project that the documentation depends to be consistent with an ONAP release.
    • CI/CD Documentation Tool Chain
      • The tool chain to create document artifacts will include gerrit, jenkins, and nexus the same as software projects and add specific tools appropriate for documentation.
      • Where there are published documentation depends on source in a repository, the tool chain will support the integration - e.g. to propagate changes in APIs into the documentation. 
  • Please provide the full intended scope of the project; not just what is intended for the project's first release.
    • First release establishes best practices and pattern for managed documentation as well as the documentation for ONAP release 1.
    • Subsequent releases will be required for all projects to comply with practices, complete content for all audiences, address how documents might be tailored or translated for use in different ONAP instances, etc.
    • Training is not part of this project
  • Identity a list of features and functionality will be developed.
    • Documentation managed with the same pattern as source code including gerrit, jenkins, artifacts published in nexus or readthedocs.org, etc.
    • Output documentation format TBD - likely static html and .pdf versions with hyperlinks between the different documents as appropriate..
    • Depending on the volume of documentation, some indexing/ search capabilities may be provided.Curate/Edit/Organize Documentation - provided by committers and contributors to documentation project for each ONAP release including
      • 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. 
      • 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 in an ONAP release (org.onap.doc repository).
      • Creating/Maintaining 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 of the sub-repository with other projects providing the source material.
      • 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 configured to build documentation any time a 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.
    • 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 pattern for creating 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?
    Image Removed
  • Dependencies with all projects providing source material for documentation.
    • Code changes may drive documentation changes.
    • Some documentation e.g. VNF Requirements may need to be traceable to code modules (e.g. test cases)  
    • Target use cases drive the user audience and task requirements  
    Creates 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 identify use Linux Foundation best practices for a documentation tool chain by looking at other open source projects (eg. based on experience with open daylight , and opnfv).
  • Are there dependencies with other open source projects?Evaluate use of readthedocs.org as way of publishing documents.

Resources:

Other Information:

Key Project Facts

Project Name:

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

Repo names:

docsdoc
docsdoc/tools
docsdoc/source/admin
docs/source/design
docs/source/test
docs/source/platformdev
docs/source/vnfdev
docs/source/serviceprovidersources/<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: