Skip to content
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

Reorganization/cleanup of docs #1494

Closed
wants to merge 54 commits into from

Conversation

kimberscott
Copy link
Contributor

As a new OpenAPS user I spent a lot of time reading the docs, and found some of the organization confusing - e.g., classification of various reference material under "While You Wait For Gear," information split or duplicated across various setup and troubleshooting sections. Some very helpful information was hard to find on my own initially (e.g., how to actually use a profile after updating the pump) - people very graciously helped me (thanks!) but shouldn't have had to. It seems like the docs were clearly organized at one point, but have grown organically for some time to the point where that wasn't as evident to a newcomer, and were ready for a routine cleanup.

Here is a proposed reorganization; you can see it hosted at https://draft-openaps-reorg.readthedocs.io/ I have tried not to change anything substantive or remove any information in this PR, although I've added some minor clarifications in places. The main changes are:

  • Consolidating info about hardware (what to get, how to put it together, how to improve battery life of Pi, etc.)
  • Consolidating flashing instructions for Mac, Windows, & all platforms and separating out the "how to log in over serial" instructions
  • Separating "While You Wait For Gear" and "Customize-Iterate" headers into preparation, "how it works," "usage/maintenance", and "customization/advanced" sections for clarity in referencing later. The preparation section still includes a reading list of what pieces you should read and understand before installing/using OpenAPS, which I think will be easier to maintain than notes in pages on e.g. monitoring the rig that you don't need to understand everything yet. If there are additional particular sections it's important to read, skim, or be aware of ahead of time they can just go on the reading list.
  • Organizing the two autotune pages more clearly into "how it works" and "how to make it go"
  • Making some information about day-to-day usage more prominent ("Tips and Tricks" which was hiding in Resources had some info I'd seen asked about repeatedly; some were moved to appropriate sections and rest were made into a section in usage/maintenance)
  • Clarifying the overview of steps. As noted in the commit this is more like personal taste, but as a beginner I found the image at https://openaps.readthedocs.io/en/latest/docs/Understanding%20OpenAPS-Overview/overview-of-build-process.html very confusing and, even though some people strongly prefer pictures over text, I'm concerned this would confuse other people too. (I ran this by other people locally, but admit the people I know skew text-preferring.)

Obviously happy to make (/remove) any changes as requested, and to handle merging in existing PRs if that would be helpful, as I think I touched basically every file and will have caused merge conflicts.

Kim Scott added 30 commits August 9, 2019 15:56
…bility (tradeoff: sidebar toctree isn't kept always 'expanded' via explicit listing of contents, but allows straightforward "summary" text for main headings in the index file)
…luding parts, how to put them together, antenna info for edison
…you wait for gear"; preserve instruction to learn these things before installing openAPS by adding a (placeholder) 'reading list' section to the prep section
…pics previously in 'while you wait for gear'
…ste than some of the other organizational efforts; e.g., removing the overview-of-steps image because I found it substantially more confusing than helpful (even though it looks very snazzy) and replacing with a text-based overview indicating that hardware and other prep can be done in parallel, then you install, then you'll likely do some additional customization. Keeping these changes separate, & not changing any filenames, in case anyone wants to cherry-pick around this one.
…e easier to find; rename section, recommend reading when done with installation process
…dings. Remove now unused subdirectory index.rst files; shift any content in those to section overviews.
Kim Scott added 24 commits September 8, 2019 18:53
… serial connection is a way to monitor a rig regardless of internet connection
…t more cleanly; include info about how to update your settings where people will hopefully see it
…prep section, not specifically for Medtronic pumps; include more detail about how that might affect automatic usage in the how it works section; consolidate several places linking to where to give feedback about Autotune
…t setup page instead of troubleshooting; put all troubleshooting info in troubleshooting page instead of split between setup and troubleshooting; put info about additional pills not to trust in the setup page
@StephenBrown2
Copy link
Contributor

This looks pretty good to me, but unfortunately work has continued and there are now many conflicts. Would you mind squashing all your commits and rebasing on master to get the updates?

@kimberscott
Copy link
Contributor Author

Of course, will do!

@kimberscott
Copy link
Contributor Author

Sorry for the delay! Closing this and replacing with #1537 which starts from the up-to-date master branch.

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

Successfully merging this pull request may close these issues.

2 participants