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
...
- 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;
a VNF developer designing, testing, and certifying a VNF for use on ONAPa 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 builds documentation artifacts for each release.
- 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 users quickly understand how to do required tasks, documentation is efficiently created/tested :
- documentation is an integral part of the design and development of an ONAP release thus
- 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:
- The first release establishes best practices and patterns for managed documentation as well as the documentation for ONAP release 1. Subsequent releases maybe required for all projects to comply with best practices, to complete content for all audiences, to address how documents might be tailored or translated for use in different ONAP instances, etc
- Describe the functionality to be provided by the project.
- Documentation artifacts for an ONAP release that contain
- original content created by contributors to 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 use gerrit, jenkins, and nexus the same as software projects and add specific tools appropriate for documentation.
- Where published documentation depends on source in any repository, the tool chain will support the automated 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. - Documentation artifacts for an ONAP release that contain
- 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.
- 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.
- Curator/Editor Functionality provided by committers and contributors to this project for each ONAP release.
- Specify any interface/API specifications proposed
- TBD the documentation tool chain selected may impose some requirements on how source material is structured in repositories that will be integrated.
- 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 providedSphinx and ReStructuredText will be used for index structure and source document contents that are built from gerrit repositories and updated at Readthedocs.
- 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 for / relationship we describe above with other projects and sources of material that are integrated in the documentation, Release 1 documentation.
- 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 providing , committees that provide 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 for a release.
- Project will identify use best practices for a documentation tool chain by looking at other open source projects (eg. open daylight, opnfv)based on open daylight and opnfv.
- Evaluate the use of swagger.io for API documentation
...
- Seed Code / Documentation -
- API Guides - MSO, AAI, APPC, Policy, Portal
- Schema - AAI
- Guidelines -
VNF Guidelines for Network Cloud,VNF Management Requirements,VNF Cloud Readiness, ONAP Logging- See also the related project proposal on VNF Requirements etc.
- User Guides -
- Developer APPC
- Service Designer - Design, Deploy, SDC
- Administrator - ONAP Portal for administrators
- Operations - Operate, VID, Policy application, DMaaP Bus Controller, ONAP Portal for users
- Tutorials - Installing and Running the ONAP Demos, Automatically Creating a Netconf Mount in APPC from SDNC
- Vendor Neutral Yes
- Meets Board policy (including IPR) Yes
...
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
...