airship-in-a-bottle/doc/source/documentation-conventions.rst

Warning

This repository is being deprecated. Project documentation has moved to the Airship Docs project, and Airship-in-a-Bottle environment will be merged into the Airship Treasuremap project.

Documentation

Each Airship 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 Airship components. The two common places for Airship 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 Airship component projects.

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

Tip

{{component name}} is part of Airship, a collection of components that coordinate to form a means of configuring, deploying and maintaining a Kubernetes environment using a declarative set of yaml documents. More details on using Airship may be found by using the Treasuremap