Documentation Guidelines Sept. 19, 2017

Overview Role & Responsibilities   Role & Responsibilities Goal: Provide quality documentation, making the process as painless as possible! Projects with source code: Release Notes and Development Guides Non-source code projects: topic-appropriate content PTLs are responsible for validating that their documentation is clear, accurate and comprehensive Doc. team liaisons will assist with technical issues and style guide, and do final reviews Guidelines All Release Notes and Development Guides go into Readthedocs Format should be in Restructured text (RsT), using ONAP Style Guide Existing documentation – goal is no rewriting API’s: easy to use tools to convert Swagger, REST Interfaces or Word docs to RsT ONAP wiki – use Pandoc to convert any change-controlled release documentation to RsT

What you need to do   By Code Freeze – M4 (Sept. 28) Code Freeze Checklist Create docs folder for your project: Setting-Up Documentation Add your repository as a submodule to docs project Add a docs folder as top level of your project Repo Set up your Development and Release Note templates: Templates and Examples Document your APIs in Restructured Text. Refer to the following examples API Examples Swagger: via swaggerv2doc directive REST Interface: via Sphinx httpdomain directive Word doc: via Pandoc utility Note - UML Sequence diagrams can be included but are optional for Amsterdam Start converting any existing change-controlled release wiki content to RsT: Converting to RST By Release Milestones RC0 (Oct. 12): Complete and validate all your Release Notes and Development guides RC1 (Oct. 26): Resolve any open issues RC2 (Nov. 09): Gain final approval from Doc. team

Development Guidelines Templates Platform Component / Services Sections to Include: Architecture Delivery Offered APIs Consumed APIS Logging & Diagnostics Installation Configuration Administration Human Interfaces SDK / Library projects Sections to include: Architecture Offered APIs Libraries Logging & Diagnostics Building Components that use SDKs

Release Notes Template Sections to include: New Features Bug Fixes (with a link to Jira) Known Issues Upgrade Notes Deprecation Notes …

Doc. Team Liaisons

Proposed Structure