Documentation re-org: Decide where in-depth tool documentation lives

[brendenpelkie]

Feature request details

Right now the only tool documentation is the build guides under 'build guides'. We need to add to this so that there are usage guides on how to do things with the software and tool as well. This is especially true for the pipette tool, where new users currently have to intuit how the whole thing works from the api docstrings. I think it makes sense to lump all of the documentation for each tool in one place, so the build guide, software setup guide, usage guide, and examples all live together. To support this I propose renaming the 'build guides' section of the documentation to 'tool guides' or similar. Also open to other thoughts on how to organize more complete tool documentation.

[sgbaird]

Sorry it took a while to get back to this!

First including prior comments from #130:

Blair from https://github.com/machineagency/science-jubilee/pull/130#issuecomment-2176930410

How do we want to organize the docs? 'Getting Started' currently primarily refers to the science-jubilee python codebase. Should we rename 'Getting Started' to 'Using science-jubilee to control your machine' or something? Then maybe we can divide the New User Guide information between the 'building a jubilee' and the software sections? I also see the utility in having a high-level end-to-end guide which gives people a sense in what needs to happen to go from nothing to an experiment.

[sgbaird]

Brenden from https://github.com/machineagency/science-jubilee/pull/130#issuecomment-2179486648

Great to see this, I didn't realize this was in progress when I added the new user guide! I think we are bumping up against some tension between having these docs be for "science-jubilee, the python package for controlling Jubilee" and "science Jubilee, the place to come learn how to do experiments with Jubilee". I would advocate for leaning into the latter in our docs and making science-jubilee docs as much of a one-stop-shop for jubilee guidance as possible. Jubilee for science is really starting to get some traction in the community, and we should make sure new users have a clear path forward when getting started. There might be other organizational schemes for this that are worth considering, but we should settle on something. (ex, split the python package docs and general guidance docs). I opened https://github.com/machineagency/science-jubilee/issues/125 with the goal of discussing this. I think we should consider how to organize the entire project as well, in addition to the docs. Are we outgrowing the current setup of having everything (code, tools, config, guidance/docs) in one github repo, or is this a simple solution that gets the job done?

Back to the original question, I think it makes sense to have an obvious landing section aimed at someone who heard about Jubilee somewhere and wants to see what it's about. This might look like the front page but with more details, maybe a text version of how we introduce Jubilee in talks/posters/etc. Then the obvious next step might be something like my 'new user guide' that gives a detailed walkthrough of how to get up and running on Jubilee, from buying the kit all the way to running an experiment. 'Getting started' might be a bit of an understatement for this section.

I'm currently onboarding 3 new Jubilee users (2 MechE students and 1 ChemE PhD student). I expect to have clearer thoughts on this in a week or so after seeing how they feel about the learning process.

[sgbaird]

Great to see this, I didn't realize this was in progress when I added the new user guide!

Thanks! That was my bad for not seeing the new user guide sooner 😅

I think we are bumping up against some tension between having these docs be for "science-jubilee, the python package for controlling Jubilee" and "science Jubilee, the place to come learn how to do experiments with Jubilee". I would advocate for leaning into the latter in our docs and making science-jubilee docs as much of a one-stop-shop for jubilee guidance as possible. Jubilee for science is really starting to get some traction in the community, and we should make sure new users have a clear path forward when getting started.

Agreed!

There might be other organizational schemes for this that are worth considering, but we should settle on something. (ex, split the python package docs and general guidance docs). I opened #125 with the goal of discussing this. I think we should consider how to organize the entire project as well, in addition to the docs.

I think it's worth some careful thought and discussing. In one sense, when someone says "I'm committed to getting a Science Jubilee", there are up-front need to knows and things that are OK if it comes later. Hardware to purchase and build/electronics/firmware/testing instructions are the up-front need to knows I think.

Are we outgrowing the current setup of having everything (code, tools, config, guidance/docs) in one github repo, or is this a simple solution that gets the job done?

It's not out of question; however, in the near-term I would caution against splitting into two GitHub repos and instead focus on finding the right organization within the GitHub repo in terms of directory structure and on the website. Hardware, electronics, software, firmware, testing, documentation, and usage instructions all have some connection with each other, so splitting it up across repositories could have some unexpected downsides, especially since it wasn't designed from the start this way.

Some examples that come to mind are Pioreactor and Rodeostat. Interestingly, Pioreactor puts their CAD files on https://www.printables.com/@Pioreactor, and has a separate repo for the docs, though the website makes it feel like most things are hosted under the same blanket.

FarmBot hosts all the CAD models on OnShape, PCB Layout/schematic on a Google Drive (linked to on CAD page), and a top-level GitHub organization that hosts repositories for a web app, Python driver, Arduino firmware, etc. (i.e., anything on that organization is specific to FarmBot). They actually have an entirely separate GitHub organization dedicated to documentation with quite a few repos: https://github.com/FarmBot-Docs.

OpenFlexure has a Gitlab organization with separation of repos:

Some random observations:

• In general (not just these examples), I've noticed is that often a Web UI will be in a separate repo, perhaps because it's easy to use full-repo templates
• Pioreactor, OpenFlexure, and FarmBot all have dedicated discourse forums

Back to the original question, I think it makes sense to have an obvious landing section aimed at someone who heard about Jubilee somewhere and wants to see what it's about. This might look like the front page but with more details, maybe a text version of how we introduce Jubilee in talks/posters/etc. Then the obvious next step might be something like my 'new user guide' that gives a detailed walkthrough of how to get up and running on Jubilee, from buying the kit all the way to running an experiment.

'Getting started' might be a bit of an understatement for this section.

"So, you want to build a Science Jubilee" 😄

I'm currently onboarding 3 new Jubilee users (2 MechE students and 1 ChemE PhD student). I expect to have clearer thoughts on this in a week or so after seeing how they feel about the learning process.

Similarly, as soon as we get the 3D printed parts from Lukes Laboratory, we'll be raring to go with four Science Jubilee builds with the AC summer students.