Documentation Playbook

The OMSF Documentation Playbook aims to make it easier for developers to integrate documentation into their projects from the very beginning. It offers guidance on the types of documentation most valuable to both developers and users, along with a companion GitHub repository that provides a ready-to-use setup for automatically generated API documentation. Together, these resources help ensure your projects are clear, accessible, and welcoming to both users and contributors.

Audience

While the guidance in this playbook applies to projects in any programming language, the accompanying OMSF_docs_template repository is structured around a Python project, and many examples throughout the text draw from Python-based codebases.

How to Use This Playbook

The Playbook is organized by the type of documentation. Each section will describe the specific piece of documentation in increasing detail with writing tips interspersed throughout. Note that the types of documentation discussed here are just what the authors recommend to have for open source software projects, especially open source scientific software projects. Some items might not be applicable to your project or your project might need documentation not explicitly mentioned.

There is a companion GitHub repository for this Playbook! It contains:

• A starting setup for using Sphinx to generate the static HTML pages that will make up your external documentation that you can copy into your own project or copy into a new repo for a new project.
• Template markdown files that can be filled out and used in the external documentation for your project.
• Ready-to-use infrastructure for automatically generating API documentation for your modules and submodules.
• Information for how to host your external documentation on Read the Docs or GitHub Pages.

More to Explore!

Are you a developer? Make sure to also check out the Developer Playbook!

Leading a software project and want to make it easier for external contributors to, well, contribute? See the Contributions Playbook.

The types of documentation highlighted in this playbook was in part inspired by the The Grand Unified Theory of Documentation, which is described in detail in this DIVIO blog post.

Want a template for a piece of documentation we didn’t include? Check out The Good Docs Project for even more documentation resources!