Skip to content

Instantly share code, notes, and snippets.

@joerg84

joerg84/documentation-guide.md Secret

Last active August 29, 2015 14:23
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save joerg84/9d1821b745ae8c8f289e to your computer and use it in GitHub Desktop.
Save joerg84/9d1821b745ae8c8f289e to your computer and use it in GitHub Desktop.
Download ZIP
Raw
documentation-guide.md

Mesos Documentation Style guide

Documentation is an integral part of every good feature as it describes the intended usage and enable new users to start using and understanding the feature.

We have three different kinds of documentation:

  1. MarkDown User Guides

User guides and non-code technical documentation is stored in markdown files in the docs/ folder. These files get rendered for the online documentation.

  1. Doxygen API Documentation and Developer Guides as part of source code

Doxygen API documentation needs only to be applied to source code parts that constitute an interface for which we want to generate Mesos API documentation files. Implementation code that does not participate in this should still be enhanced by source code comments as appropriate, but these comments should not follow the doxygen style.

Substantial libraries, components, and subcomponents of the Mesos system such as stout, libprocess, master, slave, containerizer, allocator, and others should have an overview page in markdown format that explains their purpose, overall structure, and general use. This can even be a complete developer guide.

  1. Regular source code Documentation

All other source code comments must follow the Google Style Guide.

Conventions

We follow the IETF RFC2119 on how to use words such as "must", "should", "can", and other requirement-related notions.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment