Merge pull request #874 from marionbarker/working-docs

Incorporate Reviewer Comments - post 3.4.x release
LoopKit · Nov 23, 2024 · 8ee7a1b · 8ee7a1b
2 parents 385f300 + 36e4f75
commit 8ee7a1b
Show file tree

Hide file tree

Showing 20 changed files with 2,309 additions and 2,509 deletions.
diff --git a/docs/browser/build-yml.md b/docs/browser/build-yml.md
@@ -14,7 +14,7 @@
         * Add them in [Users and Access](https://appstoreconnect.apple.com/access/users){: target="_blank" } on App Store Connect.
         * Add them to your *TestFlight* Internal Testing group.
 
-    [<span class="loop-bigger">:material-skip-forward:</span>](tf-users.md#set-up-users-and-access-testflight) To skip the detailed instructions, click on [Set Up Users and Access (TestFlight)](tf-users.md#set-up-users-and-access-testflight).
+    [<span class="loop-bigger">:material-skip-forward:</span>](tf-users.md#testflight-users-overview) To skip the detailed instructions, click on [*TestFlight* Users Overview](tf-users.md#testflight-users-overview).
 
 Refer to the graphic below for the first four steps:
 

diff --git a/docs/browser/img/gh-fork-loopworkspace.svg b/docs/browser/img/gh-fork-loopworkspace.svg
diff --git a/docs/browser/intro-summary.md b/docs/browser/intro-summary.md
@@ -41,7 +41,7 @@
     * *GitHub*:
         * [`Action: 3. Create Certificates`](certs.md#create-certificates){: target="_blank" }
         * [`Action: 4. Build Loop`](build-yml.md#build-the-loop-app){: target="_blank" }
-    * _<span translate="no">Apple</span>_: [Set up `Internal TestFlight Group`](tf-users.md#set-up-users-and-access-testflight){: target="_blank" }
+    * _<span translate="no">Apple</span>_: [Set up `Internal TestFlight Group`](tf-users.md#testflight-users-overview){: target="_blank" }
     * Phone: [Install the *Loop* app using the *TestFlight* app](phone-install.md){: target="_blank" }
 
 ???+ question "FAQs (click to open/close)"

diff --git a/docs/browser/other-apps.md b/docs/browser/other-apps.md
@@ -397,7 +397,7 @@ Please do not remove an existing app if you have trouble building a new one. You
 
 ## Add Users to *TestFlight* for App
 
-Once the first build completes, you will be able to configure *TestFlight* for the app - follow the template for setting up *TestFlight* for Loop found in [Configure to Use Browser: Set Up Users and Access (TestFlight)](../browser/tf-users.md#set-up-users-and-access-testflight).
+Once the first build completes, you will be able to configure *TestFlight* for the app - follow the template for setting up *TestFlight* for Loop found in [Configure to Use Browser: *TestFlight* Users Overview](../browser/tf-users.md#testflight-users-overview).
 
 ## Install on Phone
 

diff --git a/docs/browser/phone-install.md b/docs/browser/phone-install.md
@@ -1,12 +1,10 @@
 ## General Installation Information
 
-This is only available with&nbsp;_<span translate="no">Loop 3</span>_.
+**The *Loop* app must be built at least every 90 days when using a browser to build.** With version 3.4.0 and later, the build is automatic (once a month or with a new release). It is recommended you manually install the new build using *TestFlight* at your convenience.
 
-**The *Loop* app must be built at least every 90 days when using a browser to build.** With version 3.4.0 and later, the build is automatic. It is recommended you manually install the new build using *TestFlight* at your convenience.
+After you [Build the *Loop* App](../browser/build-yml.md#build-the-loop-app) with a browser and you get the email that it is availble in *TestFlight*, you are ready to install on as many phones as you and your family members need.
 
-After you [Build the *Loop* App](../browser/build-yml.md#build-the-loop-app) with a browser and it has automatically uploaded to the *TestFlight* app, you are ready to install on as many phones as you and your family members need.
-
-* If you later need to add an adult family member to your list, refer to [Set Up Users and Access (TestFlight)](../browser/tf-users.md#set-up-users-and-access-testflight).
+* If you later need to add an adult family member to your list, refer to [*TestFlight* Users Overview](../browser/tf-users.md#testflight-users-overview).
 
 * Children (under 13 in US, varies by country) cannot use *TestFlight* with their ID. When you use [*TestFlight* for a Child](#testflight-for-a-child), you will need to use your ID on their phone (not the whole phone - just the Media & Purchase portion), so send the *TestFlight* invitation to the email associated with your ID.
 
@@ -26,7 +24,11 @@ To install *TestFlight*, refer to the GIF below:
 
 ## Install App with *TestFlight*
 
-Once you get an email that the *TestFlight* processing completed, you can install the app on your phone. Note this can be half-hour to an hour after the build displays the green check mark on your browser.
+Once you get an email that your app is available to test on iOS and watchOS, you can install the app on your phone from *TestFlight*.
+
+* Note this can be half-hour to an hour after the build displays the green check mark on your browser
+* Once the app is on your phone, you can choose to install the watch version using your phone *Watch* app
+* If you did not already add your email to your *TestFLight* group for your app, go and do it now using these [instructions](tf-users.md#configure-testflight-group-for-the-app){: target="_blank" }
 
 The first time you use *TestFlight* on any phone associated with a given email, you must `Redeem` the code sent to that email inviting you to test the app. The GIF below is for someone who has never used *TestFlight*.
 
@@ -40,11 +42,12 @@ The first time you use *TestFlight* on any phone associated with a given email,
 
 If you already have the&nbsp;_<span translate="no">Loop</span>_&nbsp;app on the phone, you'll see the warning about possible loss of data. Don't worry, all your settings remain. Go ahead with the installation.
 
-* If you are building&nbsp;_<span translate="no">Loop</span>_&nbsp;3.x over&nbsp;_<span translate="no">Loop</span>_&nbsp;2.x, you will be required to go through [Onboarding](../loop-3/onboarding.md)
-
 ### Subsequent Times on Phone
 
 * Open the *TestFlight* app and find the name you used for your *Loop* app in the [Create *Loop* App in App Store Connect](../browser/prepare-app.md#create-loop-app-in-app-store-connect) step
+* If you have previously used *TestFlight* on this phone and don't see the latest build, sometimes quitting and restarting *TestFlight* will bring that new build into the list of available apps
+* Most people will just tap install to get the most recent build
+    * If you have more than one version number available in *TestFlight* you can choose which version to install by tapping on the `Previous Builds` row and then selecting the desired version
 * Tap on Install
     * If you already have the *Loop* app installed on this phone, you will be warned that the app already exists on your phone and that you might lose data
     * Click Install again (your pump connection and all your data will be fine)
@@ -56,15 +59,17 @@ If you already have the&nbsp;_<span translate="no">Loop</span>_&nbsp;app on the
 
 ## Automatic Update, Build, Install
 
-The instructions on the [Configure to Use Browser](intro-summary.md) page will, unless you make a change, automatically take the following actions for released versions 3.4.0 and later:
+The instructions on the [Configure to Use Browser](intro-summary.md){: target="_blank" } pages will automatically take the following actions for released versions 3.4.0 and later:
 
-* Update the version of your&nbsp;<span translate="no">fork</span>&nbsp;within a week of the change
-    * When an update to the default `branch`, typically `main`, is detected, a new build is created automatically and uploaded to *TestFlight*
-* Build the app at least once a month and upload to *TestFlight*
+* Update the version of your&nbsp;<span translate="no">fork</span>&nbsp;within a week of a new release release
+    * Automatically create a new build and upload it to *TestFlight*
+    * This is only for the `default` branch, typically `main`
+* Build the app at least once a month and upload it to *TestFlight*
 
-It is already true that, unless you make a change, the default setting will:
+Unless you make the recommended one-time change to [Disable Automatic Install from *TestFlight*](#disable-automatic-install-from-testflight), the default setting for each app found in *TestFlight* is to:
 
 * Install each new build from *TestFlight* on the phone as soon as it is detected
+* That's fine for some apps, like *LoopFollow*, but you do not want an app that controls your insulin delivery to install when you are not paying attention
 
 ### Recommendation
 
@@ -92,10 +97,10 @@ When you are ready to install, just open the *TestFlight* app and click Install
 
 ### Previous Builds
 
-If you tap on the bottom row that says `Previous Builds`, highlighted by the dashed-green rectangle, you can view and choose an older (or lower version number) build (as long as it has not expired). 
+If you tap on the row that says `Previous Builds`, highlighted by the dashed-green rectangle in the graphic above, you can view and choose an older (or lower version number) build (as long as it has not expired). 
 
 * In some cases, you need to do this to see the newest build
-* For example, it you build version 3.5.0 (`dev` branch) accidentally and then switched to 3.4.x (`main` branch), *TestFlight* shows you the 3.5.0 version on the screen and you need to go to previous builds to find your newer 3.4.x build
+* For example, if you built version 3.5.0 (`dev` branch) and then switched to 3.4.x (`main` branch), *TestFlight* shows you the most recent 3.5.0 version as the default build to install and you need to go to previous builds to find your newer 3.4.x build
 
 ### Unexpected *TestFlight* Beta Expiration
 
@@ -122,7 +127,9 @@ If you tap on the bottom row that says `Previous Builds`, highlighted by the das
 
 ## *TestFlight* for a Child
 
-The adult (*Apple Developer Account* owner) can log into Media & Purchase (see steps below) without affecting the child *Apple* ID associated with a phone (and thus their health records used by the *Loop* app). After the adult installs or updates the app using *TestFlight*, they probably should reverse those steps to remove their credentials from Media & Purchase.
+Minor children are not allowed to install or use the *TestFlight* app.
+
+An adult, who is a member of the [Internal *TestFlight* Group](tf-users.md#configure-testflight-group-for-the-app){: target="_blank" :} can log into Media & Purchase (see steps below) without affecting the *Apple* ID associated with a phone (and thus the health records used by the *Loop* app for the minor child). After the adult installs or updates the app using *TestFlight*, they probably should reverse those steps to remove their credentials from Media & Purchase.
 
 Media & Purchase affects access to the App Store, Books, Music and Podcasts.
 
@@ -134,7 +141,7 @@ On the Child phone:
     * Tap on Media & Purchases
     * Tap on Sign Out, and confirm
     * Sometimes the phone requires a reboot before you can sign in with a different ID
-* Sign in with the adult (*Apple Developer* Account owner) *Apple* ID and password
+* Sign in with the adult *Apple* ID email and password
 * Install or Update the app from *TestFlight* on child phone
 * Repeat the process to sign out the adult and (if needed) sign back in the child
 

diff --git a/docs/browser/prepare-fork.md b/docs/browser/prepare-fork.md
@@ -21,7 +21,9 @@
     * If you already have a fork, you cannot proceed, see [Already Have a LoopWorkspace](#already-have-loopworkspace)
 1. Now your screen should look like the graphic below
     * Your username will be automatically filled in as the owner (`Owner`)
-    * <code>LoopWorkspace</code> is the repository name (`Repository Name`)
+    * <code>LoopWorkspace</code> is the repository name (`Repository Name`) highlighted with the blue rectangle
+        * Do not rename the repository to something else
+        * It needs to match the original repository name or automatic building will not work
     * Leave the selection that says "`Copy the main branch only`" checked
     * Click on the green `Create fork` button
 

diff --git a/docs/browser/tf-users.md b/docs/browser/tf-users.md
@@ -1,42 +1,58 @@
-## Set Up Users and Access (TestFlight)
+## *TestFlight* Users Overview
 
-> You repeat this step if you need to add a User to your account. For example, you want to add another adult who can install the app on your child's phone or you want a spouse or friend to have a copy of the app on their phone as backup for a trip.
+There are two parts to this.
 
-> As a developer, you are already included as a user with the Role of Account Holder, Admin. But you will need to add yourself to the TestFlight group for your App.
+* A user must be registered under your [Your App Store Connect User List](#your-app-store-connect-user-list) before they can be added to a *TestFlight* internal test group for any app
+    * As a developer, you are already included as a user with the Role of Account Holder, Admin
+* Once the first build for a given app completes, you will be able to configure the [*TestFlight* Internal Testing Group](#configure-testflight-group-for-the-app) for that app
+    * You must add yourself to the *TestFlight* Internal Testing Group for each app
 
-Once the first build completes, you will be able to configure *TestFlight* for the app.
+## Your App Store Connect User List
 
-!!! tip "Add Each Users One Time"
-    Once you add a user to have access to your TestFlight for this app, you don't need to do it again - it remains available to them across rebuilds and different versions for that app.
+!!! tip "Step 1: add user for access for any of your apps"
+    Before you can select someone for the *TestFlight* Internal Testing group for any app, you must first add them to your App Store Connect User list.
 
-You are configuring a private capability for your family using an Internal Testing group. You need the *Apple ID* email address for each adult installing from your build. When building for a child, you will use your own *Apple ID*, not theirs. See [*TestFlight* for a Child](phone-install.md#testflight-for-a-child).
+    As a developer, you are already included as a user with the Role of Account Holder, Admin.
 
-1. First you need to add the email address(es) to your *App Store Connect* Access Users list:
+You are configuring a private capability for your family using an Internal Testing group. You need the *Apple ID* email address for each adult installing from your build. When building for a child, you will use an adult's *Apple ID*, not theirs. See [*TestFlight* for a Child](phone-install.md#testflight-for-a-child).
 
-    * Open this link: [Users and Access](https://appstoreconnect.apple.com/access/users){: target="_blank" }
-        * You must provide a role for each person - `Customer Support` is a good choice
-        * Once you have added them here, you'll be able to select them in the `TestFlight` group for your app
+First you need to add the email address(es) to your *App Store Connect* Access Users list:
 
-    ![add email and role for your users](img/add-users.png){width="700"}
-    {align="center"}
+* Open this link: [Users and Access](https://appstoreconnect.apple.com/access/users){: target="_blank" }
+    * You must provide a role for each person - `Customer Support` is a good choice
+    * Once you have added them here, you'll be able to select them in the `TestFlight` internal test group for each of your apps
+
+![add email and role for your users](img/add-users.png){width="700"}
+{align="center"}
+
+## Configure *TestFlight* Group for the App
+
+!!! tip "Add user for each app"
+    Once you add a user to have access to your TestFlight internal test group for an app, you don't need to do it again - it remains available to them across rebuilds and different versions for that app.
+
+1. Open this link: [App Store Connect / Apps](https://appstoreconnect.apple.com/apps){: target="_blank" } to view your apps; log in if needed.
 
-1. Open this link: [App Store Connect / Apps](https://appstoreconnect.apple.com/apps){: target="_blank" } to view your apps; log in if needed. Then select your *Loop* app. Click on the `TestFlight` tab then click the blue plus button (<font color="#2997FF">:material-plus-circle:</font>) next to `Internal Testing` to add a group.
+    * Select your *Loop* app
+    * Click on the `TestFlight` tab
+    * **If you already have an Internal Testing Group for this app, skip to Step 4**
+
+1. Click the blue plus button (<font color="#2997FF">:material-plus-circle:</font>) next to `Internal Testing` to add a group.
 
     ![open TestFlight tab for your app](img/setup-testflight-01.png){width="700"}
     {align="center"}
 
 1. Fill out the name you want for the `Internal Testing` group
     * Be sure to check the box `Enable automatic distribution`
-    * Click `Create` when done (this can always be modified later)
+    * Click `Create` when done
 
     ![add email and role for your users](img/setup-testflight-02.png){width="700"}
     {align="center"}
 
-1. As soon as you create the group, you'll be asked who should be included
+1. You can add or remove emails to the Internal Test Group as any time
     * Click in the box beside each person you want to include
     * Each person in this group will get an email each time you update (build again) using the <code>*GitHub* Browser Build</code> method
     * Click `Add` when you are done
-    * If building for a child, you will send the invitation to yourself because you will install for your child: See [TestFlight for a Child](phone-install.md#testflight-for-a-child)
+    * If building for a minor child, you will send the invitation to yourself or another person because a minor child is not authorized to use *TestFlight*: See [TestFlight for a Child](phone-install.md#testflight-for-a-child)
 
     ![select your users for the testing group](img/setup-testflight-03.png){width="700"}
     {align="center"}

diff --git a/docs/faqs/algorithm-faqs.md b/docs/faqs/algorithm-faqs.md
@@ -108,5 +108,5 @@ There is more detail about the Loop Algorithm at the bottom of the Operate tab.
 * [Algorithm Overview](../operation/algorithm/overview.md)
     * [Bolus Recommendations](../operation/algorithm/bolus.md)
     * [Blood Glucose Prediction](../operation/algorithm/prediction.md)
-    * [Automatic Adjustments](../operation/algorithm/temp-basal.md)
+    * [Automatic Adjustments](../operation/algorithm/auto-adjust.md)
 
diff --git a/docs/faqs/glossary.md b/docs/faqs/glossary.md
@@ -158,6 +158,8 @@ When Google Translate is selected:
 
 **<span translate="no">Monterey</span>**&nbsp; (Monterey): operating system for Mac, macOS 12.x
 
+**<span translate="no">MPC</span>**&nbsp; (MPC): model predictive control; the type of control algorithm used by Loop
+
 **<span translate="no">NFC</span>**&nbsp; (NFC): Near-Field Communication is used for scanning devices such as Libre sensors
 
 **<span translate="no">Nightscout</span>**&nbsp; (Nightscout): a personal website used to view your glucose and diabetes management data, `Loop` can upload to `Nightscout`

diff --git a/docs/loop-3/displays-v3.md b/docs/loop-3/displays-v3.md
@@ -64,7 +64,7 @@ Below the chart you will see an explanation of the variables Loop takes into acc
 
 * [Carbohydrates](../operation/algorithm/prediction.md#carbohydrate-effect){: target="_blank" }
 * [Insulin](../operation/algorithm/prediction.md#insulin-effect){: target="_blank" }
-* [Glucose Momentum](../operation/algorithm/prediction.md#blood-glucose-momentum-effect){: target="_blank" }
+* [Glucose Momentum](../operation/algorithm/prediction.md#glucose-momentum-effect){: target="_blank" }
 * [Integral Retrospective Correction](../operation/algorithm/prediction.md#insulin-effect){: target="_blank" } (or [Retrospective Correction](../operation/algorithm/prediction.md#retrospective-correction-effect){: target="_blank" })
 * Suspension of Insulin Delivery