Skip to content

refactor(docs): split Flex Instruction Manual into more pages #19151

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 20 commits into
base: edge
Choose a base branch
from

Conversation

ecormany
Copy link
Contributor

@ecormany ecormany commented Aug 7, 2025

Overview

The chapters of the Flex manual were great for a PDF book. They are toooooo long for web-based docs. This fixes that.

Test Plan and Hands on Testing

Sandbox.
Examining warnings from mkdocs build but not overly fussed about them now.

Changelog

  • Splits up installation, system description, modules, protocol development, software, and maintenance chapters.
  • Big rewrite of labware chapter to stop duplicating Labware Library content.
  • Moves the entire manual from flex-manual -> flex for better URLs.

Review requests

  • Check links.
  • Check prose, especially at the start and end of pages which might have retained transitions across sections that no longer make sense when they're on a separate page.
  • Please take a special look at the Labware chapter, which had the most rewriting as opposed to refactoring.

Risk assessment

low-med. docs only but could've broken some internal links or something.

@ecormany ecormany requested a review from jwwojak August 7, 2025 16:09
Copy link
Contributor

@jwwojak jwwojak left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removing all the specific labware stuff is a real improvement as is the new organization.

I only have comments about multiple instances of linked "Labware Library" references on the same page when we might be able to get away with doing that once, on first mention only.

Here's where it shows up as linked text multiple times:

  • index.md: 2
  • concepts.md: 2
  • types.md: 3

Not many instances, but when combined with other links, a page can look cluttered.

@ecormany ecormany marked this pull request as ready for review August 8, 2025 13:12
@ecormany
Copy link
Contributor Author

ecormany commented Aug 8, 2025

Ready for review. Doing a self-review (i.e., proofread and checking links) throughout the day today.

@ecormany ecormany requested a review from emilyburghardt August 8, 2025 13:13
@y3rsh
Copy link
Member

y3rsh commented Aug 8, 2025

Test this branch here:

http://sandbox.docs.s3-website.us-east-2.amazonaws.com/docs-flex-manual-refactor

Let us make sure the build and publish looks good.

image

Copy link
Collaborator

@emilyburghardt emilyburghardt left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Took a stroll through the sandbox and left a few comments- some nitpicks, mostly small things that aren't building right. can be picked up easily after this is merged, too.


When you install a pipette, you will be guided through the following steps on the touchscreen or in the Opentrons App.

1. Choose pipette type
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

super nitpick that can be ticketed for later, but in the current manual these headers (choose pipette type/ prepare for installation etc.) really pop with the different text/color. Here, they look like plain text, so we could add some different style element like we had before.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, this is directly following our web typography standards. I think we should feel free to modify if things are too same-y, to the point of making the text harder to read.

@ecormany
Copy link
Contributor Author

ecormany commented Aug 8, 2025

image

addressing these in #19163, thanks for spotting tho!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants