How to write documentation?

Some people think that project documentation will inevitably be the most important part of your project going forward. It's important to use any and all means at your disposal to document your code.

We like to write documentation in markdown using MkDocs. It provides a very nice command line interface, free static hosting, and a nice default theme with integrated search. This site is generated using MkDocs!

We focus on providing online prose documentation with tutorials and examples.

Dedicated documentation

This is likely the main entry point for new users. The dedicated documentation should first and foremost provide a higher level description of the software. It's important to give a gentle introduction but still get to the point quickly.

It should be available online, either as part a README file for small projects or more likely a full website. Liberally include code examples and if possible a short demo tutorial where the user can follow along.

API documentation (Python)

Python provides many powerful alternatives for inline documentation. We prefer a combination of docstring to explain the purpose of individual classes/methods/function with extensive type annotations. We prefer explicit type annotations over e.g. [Google style docstrings][google-docstrings] since they provide a richer syntax, allow editors to provide useful auto-completions, and will probably make you think twice before breaking.

That said, here's an example of inline Python documentation, using what's described above:

def grep(pattern: str, line: str) -> bool:
    """Match a simple pattern substring in a given string."""
    return pattern in line

For much more visit mypy.

Change log

Follow this opinionated standard dubbed "Keep a CHANGELOG". Basically it should be written in Markdown, mark each release with a version and date, and clearly separate between different categories of changes.

Flowcharts

Flowcharts can convey overview in ways that is impossible to put into words. It can be a great way to organize e.g. a pipeline of functions that will help you in the design of your project. A recommended software is the free and online tool draw.io. Another one is the python library diagrams