...
- Proposed name for the project:
Documentation - Proposed name for the repository:
org.onap.docsdoc
Project description:
...
- Create and maintain documentation targeted to ONAP user audiences and the tasks they perform. For exampleIllustrative 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;
- 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
- 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 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 user audiences will quickly understand how to do use ONAP and perform required tasks
- documentation is an integral part of the design and development of an ONAP release thus .
Scope:
- Describe the functionality to be provided by the project.
- Curator/Editor Functionality provided by committers and contributors to this 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 required for in an ONAP release in the (org.onap.docs doc repository).
- Identify sources and create Create/Update 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 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 taskReview project, planning, integration, and committee artifacts or source material early in a release looking for opportunities to align on clear end to end terminology and to test early drafts of documentation.
- CI/CD Functionality provided automatically by the tools created and/or configured by this project are triggered by a change in a source repository that the documentation depends on.doc project contributors and committers
- Gerrit, Jenkins job builder will be configured for each release to generate a new published documentation any time the top level or lower in the docs doc 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 published documentation any time the top level or lower in the docs doc repository hierarchy change. A successful build will trigger an update at Readthedocs.
- Curator/Editor Functionality provided by committers and contributors to this documentation project for each ONAP release.
- 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.
- In scope -
...
- 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 on all projects, committees that provide source material for documentation.Target use cases drive the user audience and task requirements for a release.
- 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?
- Sphinx
- ReStructuredText
- Readthedocs
- Evaluate the use of swagger.io for API documentation
...
- Primary Contact Person: Greg Glover, Rich Bennett
- Names, gerrit IDs, and company affiliations of the committers
- Rich Bennett, rb2745@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, HuaweiTo Be Added, , Nokia
- Andrei Kojukhov, andreik@amdocs.com, Amdocs
- Andrea Anderson, andrea.anderson@amdocs.com, Amdocs
- Matthew Harffy, matthew.harffy@amdocs.com, Amdocs
- Shasha Guo, guoshasha@chinamobile.com, China Mobile
- Ying Li, liyingyjy@chinamobile.com, China Mobile
- Lili Kong, konglili@chinamobile.com, China Mobile
- Names and affiliations of any other contributors
- TBD based on final requirements for Release 1
- Project Roles (include RACI chart, if applicable)
...
- JIRA project name: Documentation
- JIRA project prefix: DOC
Repo names:
docdocs
docsdoc/tools
docsdoc/sourcesources/<repos created as required for source material from other projects, committees, etc.>
...
Lifecycle State: proposal
Primary Contact:
Project Lead:
mailing list tag [docsdoc]
Committers:
rb2745@att.com
timo.perala@nokia.com
gg2147@att.com
ks0567@att.com
james.yangliu@huawei.com
konglili@chinamobile.com
...