Platform & Tools

This page is about some technical solutions (platform and tools) and technical decisions that make creating documentation easier.

1. Keep your documentation as plain text. Use some markup language, like Markdown or RestructredText.

2. Check documentation into repository.

3. Ensure your documentation system is responsive, i.e. you can view documentation on a smartphone.

An example of good and supereasy platform is readthedocs. Some companies has their own platform, i.e. DocBird at Twitter.

Markup language

You should use Markdown or RestructuredText. The former is easier while the latter has better programming languages support and cross references.

TODO comparision: Markdown vs RestructuredText

Other ideas

• Use "verbosity" option in documentation so the reader can choose the level of details described.

Problems with current approach

• generating APIdocs
• not a wiki
• long way to make an edit --> you need to go through feature requests