Merge pull request LoopKit#858 from marionbarker/working-docs

Streamline instructions for Browser Build; update iOS, macOS, Xcode for Mac Build

docs/browser/bb-overview.md

@@ -2,6 +2,7 @@
 
 * <span translate="no">Loop 3</span>&nbsp;can be built with a web browser using <span translate="no">GitHub Actions</span>
 * The app is then installed by you on your phone using the *TestFlight* app
+* If you prefer to use *Xcode* on your *Mac*, head over to [Build with *Mac*](../build/overview.md){: target="_blank" }
 
 ## Requirements
 
@@ -23,17 +24,21 @@ To build the&nbsp;_<span translate="no">Loop</span>_&nbsp;app using a browser, y
 
 ## Instructions to Build with a Browser
 
+### The Short Version
+
+Complete instructions are found at this link for those comfortable with using *GitHub* and navigating the *Apple Developer* and *Apple App Connect* pages.
+
+* [Using GitHub Actions + FastLane to deploy to TestFlight](https://github.com/LoopKit/LoopWorkspace/blob/main/fastlane/testflight.md){: target="_blank" }
+
 ### How-to Video to Build with a Browser
 
-In addition to the pages linked in [Configure to use Browser](#configure-to-use-browser), there is a narrated video of each step needed to build using a browser. (This video shows build steps for version 3.2.3 or older. Some items are simplified for version 3.4.1 and newer.)
+In addition to the pages linked below in [Configure to use Browser](#configure-to-use-browser), there is a narrated video of each step needed to build using a browser. (This video shows build steps for version 3.2.3 or older. Some items are simplified for version 3.4.1 and newer.)
 
 * [How to Build the *Loop* App With a Web Browser](https://www.youtube.com/watch?v=kiu5ho0MTW8){: target="_blank" }
 
-Click in the comments for a full index of topics.  If you have issues with a step, use the index to  advance to the relevant part of the video. Subtitles are  in English. You can choose a different language but the automatic translation feature may provide translations that are not completely accurate.
-
 ### Configure to use Browser
 
-There is a lot of information in the introduction and summary page. Please don't skip that. it should be read before you begin. The steps on these pages must be completed for you to build an app using a browser:
+The steps on these pages must be completed (in order) for you to build an app using a browser:
 
 1. [Introduction and Summary](intro-summary.md){: target="_blank" }
 1. [Collect Secrets](secrets.md){: target="_blank" }
@@ -44,6 +49,10 @@ There is a lot of information in the introduction and summary page. Please don't
 1. [Build the *Loop* App](build-yml.md){: target="_blank" }
 1. [*TestFlight* Users](tf-users.md){: target="_blank" }
 
+The pages of instructions listed above give detailed steps on how to build the *Loop* app. If you are building a different app, you can follow the detailed instructions but will need to know the Fork, App Name, Identifiers and in some cases App Group for the App you intend to build. Once you build one app, subsequent apps are much easier to build.
+
+* [Build Other Apps with Browser](other-apps.md){: target="_blank" }
+
 ## Install on Phone
 
 Instructions to install on a phone are found at:

docs/browser/identifiers.md

@@ -58,6 +58,11 @@ The `Validate Secrets` &nbsp;<span class=notranslate>Action</span>&nbsp; should
     * [Action: Validate Secrets Errors](bb-errors.md#action-validate-secrets-errors){: target="_blank" } tells you what to search for in the file
     * Resolve the error and repeat the Action: [Validate Secrets](#validate-secrets)
 
+!!! tip "Pro Tip: Validate Secrets"
+    The Action `Validate Secrets` is run every time you do any other action. Technically, you never have to run the action by itself - you could start with `Add Identifiers`.
+
+    It is easier for you (or your mentors) to diagnose if there is a problem with the `Secrets` you entered when it is run stand-alone. Once your secrets are good, they should remain good, so this does not need to be repeated.
+
 ## <code>Add Identifiers</code>
 
 !!! warning "Update to Version 3.4"

docs/browser/intro-summary.md

@@ -14,7 +14,7 @@
 
     * Use the template to [Save Your Information](intro-summary.md#make-a-secrets-reference-file){: target="_blank" }
 
-    A narrated video is available:
+    If you prefer watching your instructions, a narrated video is available:
 
     * [How to Build the *Loop* App With a Web Browser](https://www.youtube.com/watch?v=kiu5ho0MTW8){: target="_blank" }
 
@@ -46,42 +46,40 @@
 
 ???+ question "FAQs (click to open/close)"
     - **Do I need a Mac computer?** No. This can be done on any browser, although it will be easier using a computer or tablet than just using a phone.
-    - **Isn't it hard to build every 90 days?** The initial setup and installation take a lot of your focused time. But once you build, future updates and builds are automatic. You just need to keep your Apple Developer account up to date. Review any email that says a GitHub action failed - read the error and take action.
+    - **Isn't it hard to build every 90 days?** The initial setup and installation take a lot of your focused time. But once you build, future updates and builds are automatic. You just need to keep your Apple Developer account up to date. Review any email that says a GitHub action failed - read the error and take action. For more information, see [Automatic Update & Build](automatic.md){: target="_blank" }.
     - **Can you explain the new automatic building?** There's a whole page on [Automatic Update & Build](automatic.md){: target="_blank" } for more explanations
     - **Can I use this for my child?** You, as the adult, can install using *TestFlight* on your child's phone. The explicit steps are provided at [Install on Phone: *TestFlight* for a Child](phone-install.md#testflight-for-a-child){: target="_blank" }.
     - **Can I still use my customizations?** Yes. [Customize using Browser](custom-browser.md){: target="_blank" }
     - **Is there a build video?** Yes. [How to Build the *Loop* App With a Web Browser](https://www.youtube.com/watch?v=kiu5ho0MTW8){: target="_blank" }
 
-## Automatic Build of Loop
-
-When you follow the directions to configure building with a browser, for Loop 3.4 and later, you configure your app to automatically build at least once a month. You also configure your app to be updated within one week of a new release, in other words, when the LoopKit/LoopWorkspace main branch is updated. For details, see [Automatic Update & Build](automatic.md){: target="_blank" }.
-
 ## Tips and Tricks
 
 The steps to configure for building with a browser requires a lot of focused attention. Take it in steps and take breaks as needed. Some people prefer a video. Some people prefer more detailed steps on a webpage and others only high-level steps. 
 
-### How-to Video to Build with a Browser
+### The Short Version
+
+Complete instructions are found at this link for those comfortable with using *GitHub* and navigating the *Apple Developer* and *Apple App Connect* pages.
+
+* [Using GitHub Actions + FastLane to deploy to TestFlight](https://github.com/LoopKit/LoopWorkspace/blob/main/fastlane/testflight.md){: target="_blank" }
+
+### The Video Version
 
-There is a narrated video of each step needed to build using a browser. This video was created for version 3.2.x and some steps have been simplified with version 3.4.x.
+If you prefer watching your instructions, there is a narrated video of each step needed to build using a browser. This video was created for version 3.2.x and some steps have been simplified with version 3.4.x.
 
 * [How to Build the *Loop* App With a Web Browser](https://www.youtube.com/watch?v=kiu5ho0MTW8){: target="_blank" }
 
 Click in the comments for a full index of topics.  If you have issues with a particular section, use the index to advance to the relevant part of the video. Subtitles are in English. You can choose a different language but the automatic translation feature may provide translations that are not completely accurate.
 
-### Section Summaries
+### The Detailed Version
+
+If you prefer seeing step-by-step instructions, those are provided too.
 
 Some sections have a Section Summary for those who just want high-level steps without a lot of graphics. It also provides a high-level view of what you are going to do before you do it.
 
 * To view the summary, click on the summary header
 * If the summary is all you need, use the `skip forward` symbol (<span class="loop-big">:material-skip-forward:</span>) to skip to the next instruction
 * Or follow the detailed instructions below the summary
 
-### Sparse Instructions
-
-For sparse instructions, with no graphics or hand-holding, click on the link below:
-
-* [LoopWorkspace Build Instructions](https://github.com/LoopKit/LoopWorkspace/blob/main/fastlane/testflight.md){: target="_blank" }
-
 ## Save Your Information
 
 **Everyone needs to read this section!**
@@ -151,6 +149,10 @@ through
 
 ## SECRETS BELOW:
 
+TEAMID
+<looks like this>
+AAAAAAAAAA
+
 FASTLANE_ISSUER_ID
 <looks like this>
 AAAAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAAA
@@ -177,10 +179,6 @@ MATCH_PASSWORD
 <looks like this>
 AnyThingYouWant-sameForEveryRepository
 
-TEAMID
-<looks like this>
-AAAAAAAAAA
-
 ## Repository Names for my Fork:
 
 https://github.com/my-github-username/LoopWorkspace
@@ -192,30 +190,24 @@ Add additional apps here if you decide to build any
 
 The <code>*GitHub* Browser Build</code> may use new and unfamiliar **terms**.
 
+These instructions can be used without knowing what any of these terms mean. But if you are curious:
+
 Some of these **terms** have ToolTips, so hover your mouse over those - or review them in the [Glossary](../faqs/glossary.md){: target="_blank" }.
 
 * Some terms in the Glossary are not in alphabetical order to improve logical grouping. All the individual <code>Secrets</code> are listed after <code>Secrets</code> in the Glossary.
 
 * `Actions`: available in your *GitHub* account to build your app (once you configure your repository)
-    * With `Loop 3`, the actions: `Validate Secrets`, <code>Add Identifiers</code>, `Create Certificates`, and `Build Loop` enable users to build the *Loop* app from a browser on any computer
-    * If <code>*GitHub* Browser Build</code> Actions are not operating as you expect, check [*GitHub* Status](https://www.githubstatus.com/){: target="_blank" } to see if it is *GitHub* problem.
+    * You must be logged in to *GitHub* to run the actions
 * <code>Secrets</code>: are required to enable *GitHub* to build the *Loop* app using *GitHub* Actions
     * Six <code>Secrets</code> must be added to your fork of LoopWorkspace
     * These <code>Secrets</code> work for any branch in your fork (`main` or `dev`, for example)
-    * These <code>Secrets</code> can be added to [Other Apps](other-apps.md){: target="_blank" } configured with the same <code>*GitHub* Browser Build</code> method
-    * For those who feel confident using *GitHub*, there are optional instructions to configure a free organizational account (for your personal use) that allows you to enter the <code>Secrets</code> only once, see [Use a *GitHub* Organization Account](other-apps.md#use-a-github-organization-account){: target="_blank" }, and have them available for every repository in that organization account
+    * If you build [Other Apps](other-apps.md){: target="_blank" }, they use the same <code>Secrets</code>
+    * For those who feel confident using *GitHub*, there are optional instructions to configure a free organizational account (for your personal use) that allows you to enter the <code>Secrets</code> only once and have them available for every repository in that organization account; see [Use a *GitHub* Organization Account](other-apps.md#use-a-github-organization-account){: target="_blank" }
 * API `Key`:`Application Programming Interface Key`
-    * You obtain and save this key from the *Apple Developer* website
+    * You create an API key from the *Apple Developer* website
     * Doing this provides 3 of your <code>Secrets</code>
-    * It is required to enable your *GitHub* account to interface with *Apple* to create your app
-* `Identifiers`: are required to build the *Loop* app with <code>*GitHub* Browser Build</code> (these are automatically generated for you)
-    * Four Identifier Names must be associated with your `App Group`
-        * `Loop`, `Loop Intent Extension`, `Loop Status Extension` and `Loop Widget Extension`
-    * Two Identifier Names will exist but do not require that association
-        * `WatchApp` and `WatchAppExtension`
-    * The `Identifier` screen, has **`NAME`** and **`IDENTIFIER`** columns
-        * If you previously built with Xcode, the items in the **`NAME`** column may start with `XC`
-        * The items under the **`IDENTIFIER`** column match the table in [Add `App Group` to Identifiers](prepare-app.md#add-app-group-to-identifiers){: target="_blank" }
+    * These secrets enable your *GitHub* account to interface with *Apple* to create your app
+* `Identifiers`: are required to build the *Loop* app with <code>*GitHub* Browser Build</code> (these are automatically generated for you) when you run `Add Identifiers`
 * [`App Store Connect`](https://appstoreconnect.apple.com){: target="_blank" }: a website available for *Apple Developer*s to review apps build with your *Apple Developer* account
     * Once you purchase an *Apple Developer* annual account, you are an *Apple Developer* and have access to this site
     * Most Loopers will not have an App until using the <code>*GitHub* Browser Build</code>