kopia lustrzana https://dev.funkwhale.audio/funkwhale/funkwhale
39 wiersze
1.7 KiB
ReStructuredText
39 wiersze
1.7 KiB
ReStructuredText
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.
|
|
|