Jump to: navigation, search

Difference between revisions of "Documentation/Checklist"

(Official book titles and title abbreviations)
(Documentation checklist)
Line 24: Line 24:
 
| Title || Title is correct. Look below for the official titles. ||  
 
| Title || Title is correct. Look below for the official titles. ||  
 
|-
 
|-
| Code samples || Code samples are in separate files. ||  
+
| Code samples || Code samples are in separate files and included in chapter, section, or appendix file. ||  
 +
|-
 +
| Chunking || Chapters and appendices are in separate files and included in the book file. ||
 +
|-
 +
| Source file names || Source file names use file naming conventions. Book files = bk_*; Chapter files = ch_*; Appendix files = app_*; Section files = section_*. ||
 +
 
  
 
|}
 
|}

Revision as of 14:54, 24 June 2013

Documentation checklist

Work-in-progress

When you write documentation, use this checklist to ensure quality.

Task Description Complete?
pom.xml file Your pom.xml file uses the latest (non-SNAPSHOT) cloud-doc plugin version and is configured correctly. To find the version number of the latest plugin, go to Clouddocs Maven Plugin Release Notes. See notes for version 1.7.1 for information about new pom.xml file configuration directives.
TOC Your pom.xml file configures a TOC for your book.
Spellcheck Oxygen has a spellchecker. You can spellcheck all files in a book by choosing Edit > Check Spelling in Files.
Glossary Embed the shared glossary and mark terms with the <glossterm> tag in your document.
Doc conventions Your content uses the recommended doc tagging.
Preface Your book has a preface.
Doc history The preface includes the doc history. Also make sure that you have included a revision entry for your latest changes.
Title Title is correct. Look below for the official titles.
Code samples Code samples are in separate files and included in chapter, section, or appendix file.
Chunking Chapters and appendices are in separate files and included in the book file.
Source file names Source file names use file naming conventions. Book files = bk_*; Chapter files = ch_*; Appendix files = app_*; Section files = section_*.


Official book titles and title abbreviations

The titles are for the HTML and PDF outputs. The title abbreviations are for the PDF output only.

Installation guides

Audience: Cloud operators

Title Title abbreviation
OpenStack Basic Installation Guide for Ubuntu 12.04 (LTS) and Debian Wheezy Basic Install Guide for Ubuntu

12.04 (LTS) and Debian Wheezy

OpenStack Basic Installation Guide for Fedora 18 Basic Install Guide for Fedora 18
OpenStack Installation Guide for Red Hat Enterprise Linux, CentOS, and Fedora Install Guide for Red Hat
OpenStack Installation Guide for Ubuntu 12.04 (LTS) Install Guide for Ubuntu


Administration guides

Audience: Cloud operators

Title Title abbreviation
OpenStack Block Storage Service Administration Guide Block Storage Service Admin Guide
OpenStack Compute Administration Guide Compute Admin Guide
OpenStack Networking Administration Guide Networking Admin Guide
OpenStack Object Storage Administration Guide Object Storage Admin Guide
OpenStack Operations Guide Ops Guide
OpenStack High Availability Guide High Availability Guide
OpenStack Virtual Machine Image Guide VM Image Guide
OpenStack Configuration Reference (in the works) Config Reference


Application developer and user guides

Audiences:

  • Developers who build applications that run in the cloud
  • Users who manage resources and services in the cloud

Titles:

Title Title abbreviation
API Quick Start N/A
OpenStack Compute API Developer Guide for Shell and Python Compute API Dev Guide for Shell and Python
OpenStack Clients Guide (moving into the new User Guide) Clients Guide
OpenStack API Complete Reference (web page) N/A
OpenStack Block Storage Service API v2 Reference Block Storage Service API Reference
OpenStack Compute API v2 and Extensions Reference Compute API and Extensions Reference
OpenStack Identity Service API v2.0 Reference Identity Service API Reference
OpenStack Image Service API v2 Reference Image Service API Reference
OpenStack Networking API v2.0 Reference Networking API Reference
OpenStack Image Service API v1 Reference Image Service API Reference
Object Storage API v1 Reference Object Storage API Reference
OpenStack End User Guide End User Guide
OpenStack Admin User Guide (TBD) Admin User Guide (TBD)