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.

