docs: Make the documentation system easier to navigate & easier to maintain

[ethanjli]

This is a tracking issue for our project to improve our documentation system to make it easier for us to improve the documentation, and easier for users to browse the documentation.

Motivation

Currently, the planktoscope.readthedocs.io documentation site is owned by someone else, and it is an old version of documentation; we don't have full control over it. We will also need to restructure our documentation system so that we can provide documentation about every released/supported version of the PlanktoScope hardware, and about every supported version of the PlanktoScope software (which for now will only be the latest version).

Goals

• Make it easy for users to access our documentation.
• Make it easy for users to find what they're looking for in our documentation.
• Make it easy to make improvements to our documentation, and to see the resulting changes.
• Make it easy for people from FairScope to write and maintain their hardware documentation in our repository on GitHub

Steps

• docs: Figure out (and document) a way to run the documentation system locally for development #142
• docs: Include the documentation site on the PlanktoScope for offline access #150
• docs: Reduce the built size of the documentation site #183
• ci: Get Github Actions to automatically build our documentation system and deploy the result on each release channel #144
• docs/setup/hardware: Import the v2.1 hardware docs #388
• docs/project-site: planktoscope.org website is confusing with multiple hardware versions #260
• docs: Provide a clear path through the docs for users trying to get started #275
• docs/setup/hardware: Integrate the v2.6 hardware docs #389

Unresolved Questions

[ethanjli]

It looks like the only off-the-shelf solution for compressing images in MkDocs is to use Material for MkDocs (which we're using) but specifically to sponsor Material for MkDocs at a rate of $15/mo so that we have access to the private Insiders build, which provides an "optimize" plugin to compress images as part of the website build process. The $15/mo rate is more than I'm personally willing to pay for this feature right now, and @tpollina I assume we don't need the other features of the Insiders build urgently enough to justify paying this out of FairScope's budget at this time.

Instead, I'll look into writing a small and simple Python script to automatically downsize all JPEG images to a width of 1200 pixels and to do some more JPEG compression (e.g. https://planktoscope.github.io/PlanktoScope/images/manufacturing_guide/IMG_20230206_212202_209.jpg is currently uploaded at the raw size of 3928x2208 pixels, and while it's already pretty small at 468 KB, we have a lot of these kinds of images where we don't really need much visual detail and we can probably compress the JPEGs even more). Depending on how this goes, I'll probably upload the raw images to Google Drive for archival and then delete them from the repo. Doing a git clone on the PlanktoScope repo will still force the raw images to be downloaded because they're in the repository's history; but at least then the zip archive download of the repository's current state will be smaller.

[ethanjli]

https://squidfunk.github.io/mkdocs-material/setup/changing-the-logo-and-icons/ provides information about how to change the favicon of the docs site.

[ethanjli]

https://www.youtube.com/watch?v=8hOaEAkUFOo provides a useful discussion of how to make docs easier for users to use. https://shows.acast.com/ohm-podcast/episodes/ep-5-how-to-communicate-with-your-community also provides a great conversation about how to make a good documentation system for an open hardware project. One of their key insights is that the documentation is also a product.

[ethanjli]

https://github.com/backstage/mkdocs-monorepo-plugin might be a useful plugin

[ethanjli]

https://diataxis.fr/ and https://www.hillelwayne.com/post/problems-with-the-4doc-model/ provide additional useful discussion about how to organize documentation.