Integrated deployment configuration and documentation.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

documentation-conventions.rst 3.4KB


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


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:


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