docs icon indicating copy to clipboard operation
docs copied to clipboard

General reorganization and cleanup - hardware, install steps, flashing, background reading

Open kimberscott opened this issue 4 years ago • 1 comments

Replacement for previous PR https://github.com/openaps/docs/pull/1494 after integrating new changes - rebasing was a little complicated because I'd combined and eliminated some files, so this was more straightforward for me. I've manually reviewed the changes here https://github.com/openaps/docs/compare/af8322ecd17c7a112a8952010ed06ee4e240b160...openaps:master to make sure everything's up to date.

Previous description - 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/en/reapply-cleanup/index.html

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.

kimberscott avatar Feb 22 '20 21:02 kimberscott

Looks great to me, but sadly I'm not one of the main approvers. I think it's definitely in a spot where it can be reviewed/approved by @danamlewis or @scottleibrand though, once https://github.com/openaps/docs/pull/1537#discussion_r384671974 gets resolved.

StephenBrown2 avatar Feb 26 '20 18:02 StephenBrown2