Suggest: clearly explain pre-requisite reading in the documentation
Hello, I've been reading and re-reading the F-Droid documentation for developers on the website, and it's been a bit of a struggle. A lot of the information needed to complete specific tasks is covered across multiple documents, with no clear order between them.
One trick I've found when writing documents like this is to start each document with a "Synopsis" section. This should briefly describe who the document is for / what it is about, and then have two explicit sections, with the headings "What you will know after reading this document" and "What you need to know before reading this document".
Each of those should have a short bullet list of the relevant items. In the "What you need to know" list each item should link to the document that explains this concept.
I've found this helpful as both an author and a reader because:
- If the "What you will know..." list starts getting beyond 7 or 8 items it's a hint that the document might be trying to cover too much.
- It helps the author know when they have finished the document -- if it explains all the things in the "What you will know..." section then the doc is finished
- It clearly tells the reader any pre-reading they need to do
- It helps the author know what knowledge they can assume the reader already has (so multiple documents don't try and explain the same thing in slightly different ways)
- It highlights documents that might be missing -- if the author has written an entry in the "What you need to know..." section, and can't find a document to link to then you know that some important concept has not been documented yet
I hope that's helpful feedback.