Documentation Guidelines Sept. 11, 2017
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
What you need to do By Code Freeze – M4 (Sept. 28) https://wiki.onap.org/display/DW/Deliverables+for+Code+Freeze+Milestone+Checklist+Template Create docs folder for your project: http://onap.readthedocs.io/en/latest/guide/onap-developer/how-to-use-docs/include-documentation.html 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) http://onap.readthedocs.io/en/latest/templates/component-info/index.html 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
Release Notes Considerations to include: New Features Bug Fixes (with a link to Jira) Known Issues Upgrade Notes Deprecation Notes …
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
Set-Up Flow
Doc. Team Liaisons