airship/airship-in-a-bottle
Code Issues Proposed changes
39a8904663
airship-in-a-bottle/docs/source/documentation-conventions.rst
Bryan Strassner c51d75705d Provide for UCP standards and conventions 
This change intends to account for various standards and conventions
used by the undercloud components. As the topic of conventions for
any active project is naturally open ended, this set of changes does
not intend to be a complete representation.

Several of the sections identified for conventions are marked as under
development, and will not be formalized as part of this change.

Change-Id: Ideaa9ed4146f4a6dcd2d3c44037bcac2ed3755bb
2018-01-02 14:48:51 -06:00

3.4 KiB
Raw Blame History

Documentation

Each UCP component will maintain documentation addressing two audiences:

  1. Consumer documentation
  2. Developer documentation

Consumer Documentation

Consumer documentation is that which is intended to be referenced by users of the component. This includes information about each of the following:

  • Introduction - the purpose and charter of the software
  • Features - capabilies the software has
  • Usage - interaction with the software - e.g. API and CLI documentation
  • Setup/Installation - how an end user would set up and run the software including system requirements
  • Support - where and how a user engages support or makes change requests for the software

Developer Documentation

Developer documentation is used by developers of the software, and addresses the following topics:

  • Archiecture and Design - features and structure of the software
  • Inline, Code, Method - documentaiton specific to the fuctions and procedures in the code
  • Development Environment - explaining how a developer would need to configure a working environment for the software
  • Contribution - how a developer can contribute to the software

Format

There are multiple means by which consumers and developers will read the documentation for UCP components. The two common places for UCP components are Github in the form of README and code-based documentation, and Readthedocs for more complete/formatted documentation.

Documentation that is expected to be read in Github must exist and may use either reStructuredText or Markdown. This generally would be limited to the README file at the root of the project and/or a documentation directory. The README should direct users to the published documentation location.

Documentation intended for Readthedocs will use reStructuredText, and should provide a Sphinx build of the documentation.

Finding Treasuremap

Treasuremap is a project that serves as a starting point for the larger Containerized Cloud Platform, and provides context for the Undercloud Platform component projects.

Undercloud component projects should include the following at the top of the main/index page of their Readthedocs documentation:

Tip

{{component name}} is part of the containerized Local Control Plane (cLCP). More details may be found by using the Treasuremap