1. Documentation Guidelines
Sept. 11, 2017

2. Agenda 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
API’s – goal is no rewriting, use our automated tools to convert what’s already in Swagger
ONAP wiki – use Pandoc tools to convert any change-controlled release documentation to RsT

3. What you need to do
By Code Freeze – M4 (Sept. 28)
Create docs folder for your project:
Add your repository as a submodule to docs project
Add a docs folder as top level of your project Repo
Create Release Note and Development Guideline topics for your project (see suggested templates)
Document your APIs (use our automated tools to convert from Swagger)
Start converting any change-controlled release content on wiki to RsT (Release Notes, Dev Guides, Architecture)
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

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

5. Development Guidelines
Platform Component / Services
Considerations to Include:
Delivery
Offered APIs
Consumed APIS
Logging & Diagnostics
Installation
Configuration
Administration
Human Interfaces
SDK / Library projects
Considerations to include:
Offered APIs
Logging & Diagnostics
Build & Install
Libraries
Interfaces

6. Set-Up Flow

7. Doc. Team Liaisons