Versions Compared

Old Version 28

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:
    • 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 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.
      • 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



    C    ontributors:

    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: