Documentation Style Guide

End-user Documentation

End-user documentation is often the most difficult to write as it requires striking the right balance between technical and non-technical instruction. Typically, writing a document should start with you asking yourself the following question:

Why is the user reading this document?

The answer will usually be one of the following:

  • They are new to the project and are looking to learn more about it

  • They are trying to do something and are having difficulty

Documentation should be written with these two answers in mind. Information should be clearly laid out in small sections with plenty of clear examples and precise instructions. You should also try to pre-empt where the user might need to go next in order to ease their journey through the document by providing logical and relevant links to more documents.

Administrator Documentation

Funkwhale is quite a technical project and is enjoyed by people who like setting up their own systems. These users can range from experienced server administrators to hobbyists, so administrator documentation should include plenty of technical instructions with an easy-to-read explanation of each step to cover both use-cases.

Developer Documentation

Developer documentation should aim to be as technical and readable as possible. Since the reader is likely a developer themselves, providing as much technical detail as possible is the best course of action as it allows them to dive in to the project’s internals with more confidence. It is safe to assume they are used to reading more technical work.