Merge pull request #878 from marionbarker/working-docs

Encourage people to ask mentors for help if needed

Author: marionbarker

docs/browser/bb-errors.md

@@ -1,10 +1,40 @@
 ## Help with Errors
 
-If you get an error when building with a browser, use this page to figure out what to do.
+!!! important "Get Help, Not Frustrated"
+    For first-time builders, there are a lot of one-time steps that all have to be correct and many screens look similar.
 
-If you are still unsuccessful, then post your request for help along with the link to your repository. For example - this link is used to test the build instructions and generate figures for LoopDocs. You replace your GitHub username where you see `loopdocs-tester`:
+    If you are updating your build or renewing certificates, the process can be confusing and some error messages can be misleading.
 
-* [https://github.com/loopdocs-tester/LoopWorkspace](https://github.com/loopdocs-tester/LoopWorkspace){: target="_blank" }
+    If you are having trouble, don't hesitate to ask for help.
+
+    Please do NOT:
+
+    * Spend hours in frustration
+    * Rename or delete a repository
+    * Delete your GitHub account
+    * Remove your App from App Store Connect
+
+### Where to Get Help with Browser Build
+
+These are two places to ask for help, but please choose only one. You may get a faster response from Facebook, but there are mentors on both sites:
+
+* [LoopandLearn Facebook Group](https://www.facebook.com/groups/LOOPandLEARN){: target="_blank" }
+* [Zulipchat: Loop: Build Help]( https://loop.zulipchat.com/#narrow/channel/148543-Loop/topic/Browser.20Build){: target="_blank" }
+
+### What Information is Needed for Help
+
+1. Your GitHub username (required):
+
+    * You can also provide a link to your repository like the example, but substitute your username for `USERNAME`
+    * If you are building an app other than Loop, replace LoopWorkspace with the app repository name
+
+    ```
+    https://github.com/USERNAME/LoopWorkspace
+    ```
+
+1. A brief summary of the step you are on and what isn't working.
+
+That's all we need to get started.
 
 Mentors can go to your public&nbsp;_<span translate="no">GitHub repository</span>_, make sure your code is up to date, examine your customizations (if any), then click on the Action tab and view your log files directly.
 
@@ -16,10 +46,10 @@ Mentors can go to your public&nbsp;_<span translate="no">GitHub repository</span
 
     All that is needed to assist is your link or as a bare minimum your *GitHub* **username**.
 
-But first - try to diagnose it yourself using this page.
-
 ### Most Common Mistakes
 
+If you get an error when building with a browser, you can use this page to figure out what to do - but don't be afraid to [ask for help](#help-with-errors).
+
 !!! warning "Just updated?"
     If you just updated to version 3.4 from version 3.2.x, you must add a new Identifier.
 

docs/browser/bb-overview.md

@@ -63,9 +63,15 @@ Instructions to install on a phone are found at:
 
 ## What if I get stuck?
 
-Try to:
+!!! important "How to Ask for Help"
+    First time setup should take several hours, but if you are having trouble:
+
+    * [Click here to find help](bb-errors.md#help-with-errors){: target="_blank" }.
+
+If you want to solve it yourself, try to:
 
 * Scroll back in the directions and see if you missed a paragraph or step
+    * Be sure you are copying the exact **names** needed for each step or clicking on the **link** associated with a particular step - many pages look similar
 * Compare your display with the <span>graphics in *LoopDocs*</span>
     * Is something different or does yours have an error message?
     * Does the [Error](bb-errors.md){: target="_blank" } message guide you to the problem and solution?
@@ -81,7 +87,6 @@ If you get an error that you cannot figure out, reach out for help before you ge
     * [Most Common Mistakes](bb-errors.md#most-common-mistakes){: target="_blank" }
     * With Browser Build, post your *GitHub* LoopWorkspace link and a brief description of your problem
 
-
 * [Errors with Browser](bb-errors.md){: target="_blank" }
 
 ## Update the App

docs/browser/bb-update.md

@@ -77,10 +77,22 @@ Under ordinary circumstances, you do not *have to* rebuild or update your *Loop*
 
     * [How to Update and Rebuild DIY Loop with a Web Browser](https://www.youtube.com/watch?v=0ipTsiqbbrQ){: target="_blank" }
 
+!!! important "How to Ask for Help"
+    Updating with Browser Build should be pretty fast and often automatic. Updating certificates (once a year) can sometimes be tricky.
+
+    If you are having trouble:
+
+    * [Click here to find help](bb-errors.md#help-with-errors){: target="_blank" }.
+
 ## Accept Agreements
 
 > This is Step 1 of 6 - it may not always be necessary, but please check every time.
 
+!!! warning "Wait After You Agree"
+    It typically takes 15 minutes before your updated agreement is available so you can complete your build.
+
+    If your build with browser fails, wait longer. An hour wait was reported by one person.
+
 Sign in to your [Apple Developer account](https://developer.apple.com/account){: target="_blank" }. If there are agreements you have not accepted, you will get errors when you try to Build that indicate your *Apple* <code>Secrets</code> are incorrect - that is very unlikely. You may also need to update your credit card information if it has changed, for example, if there is a new expiration date.
 
 * For an update, you do not need to modify the <code>FASTLANE_ISSUER_ID</code>, <code>FASTLANE_KEY_ID</code> or <code>FASTLANE_KEY</code>
@@ -99,11 +111,6 @@ Digital Service Act Compliance
     * This is a new requirement that must be completed one time
     * See [Digital Service Act Compliance](prepare-app.md#digital-service-act-compliance){: target="_blank" } for instructions
 
-!!! warning "Wait After You Agree"
-    It typically takes 15 minutes before your updated agreement is available so you can complete your build.
-
-    If your build with browser fails, wait longer. An hour wait was reported by one person.
-
 ## Renew Certificate
 
 > This is Step 2 of 6 - it is only needed once a year - you should get an email from Apple 30 days before your `Distribution Certificate` expires. (Don't worry if you did not see the email.)
@@ -117,9 +124,11 @@ Digital Service Act Compliance
 ??? question "Do you want to know more? (Click to open/close)"
     This is only a summary - please follow the detailed steps below carefully.
 
-    * Delete all your `Distribution Certificates`. Apple only allows you to have 2 of these. So get rid of the old ones so you will be able to create a new one that will last a full year. (Step 1 below.)
+    * Delete all your certificates that say the type is `Distribution`. Apple only allows you to have 2 of these. So get rid of the old ones so you will be able to create a new one that will last a full year. (Step 1 below.)
+
+    * Some people have `Distribution Managed` types listed. These are cloud-managed. An internet search finds this quote: "My general approach to cloud-managed certificates is to ignore them and let Apple’s infrastructure do its thing."
 
-    * The Certificate in question is embedded in your `Match-Secrets repository`. In order to proceed, you need to remove the old certificate from `Match-Secrets`. Later this will be automated and can be done without modifying your `Match-Secrets repository`, but for now the easiest way to do that is to just delete the `certs/distribution` folder in your current `Match-Secrets repository`.
+    * The Certificate in question is embedded in your `Match-Secrets repository`. In order to proceed, you need to remove the old certificate from `Match-Secrets`.
 
     * Finally, for every app that you build with this method, you need to run `Create Certificates` for that app. (Step 4 below.)
 
@@ -130,11 +139,12 @@ Digital Service Act Compliance
 
 1. Use this link to view your [Apple Developer Certificates](https://developer.apple.com/account/resources/certificates/list){: target="_blank" }
     * If your screen shows no Certificates and you see a message "Getting Started with Certificates", your certificate already expired and was removed by *Apple*; so skip ahead to Step 2: Navigate to your `Match-Secrets` Repository
-    * Carefully examine the `Type` column - do **not** delete a `Development Certificate`
-        * If you do not have any rows that say `Distribution Certificate`, your certificate already expired and was removed by *Apple*; so skip ahead to Step 2
+    * Carefully examine the `Type` column - do **not** delete a certificate with type of `Development`
+        * If you do not have any rows that say the type is `Distribution`, your certificate already expired and was removed by *Apple*; so skip ahead to Step 2
         * If your certificate has an expiration date several months in the future - you can wait and renew your certificate later; skip ahead to [Update `Fork`](#update-fork)
-    * Click each row that has a `Distribution Certificate` and revoke it
+    * Click each row that has a type of `Distribution` and revoke it
     * You will get an email informing you the certificate was revoked
+    * You can ignore rows with a type of `Distribution Managed`
 1. Navigate to your `Match-Secrets` Repository
     * You can do this several ways, but one method is demonstrated by the GIF below
     * Open the URL for your *GitHub* account (address is `https://github.com/username` where `username` is replaced by your *GitHub* username

docs/browser/certs.md

@@ -41,6 +41,6 @@ Once you see the green check mark by `Create Certificates`, the next step is to
 
 If this action fails, head over to the errors page. Review these links, identify and fix your error or ask for help.
 
+* [How to Ask for Help](bb-errors.md#help-with-errors){: target="_blank" }
 * [Most Common Mistakes](bb-errors.md#most-common-mistakes){: target="_blank" }
 * [Create Certificates Errors](bb-errors.md#action-create-certificates-errors){: target="_blank" }.
-* [How to Ask for Help](bb-errors.md#help-with-errors){: target="_blank" }

docs/browser/identifiers.md

@@ -58,6 +58,9 @@ 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)
 
+!!! important "Ask For Help Early"
+    Please if you are having trouble - [ask for help early by clicking on this link](bb-errors.md#help-with-errors){: target="_blank" }.
+
 !!! 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`.
 
@@ -102,6 +105,9 @@ The `Add Identifiers` &nbsp;<span class=notranslate>Action</span>&nbsp; should s
     * [Action: Add Identifiers Errors](bb-errors.md#action-add-identifiers-errors){: target="_blank" } tells you what to search for in the file
     * Resolve the error and repeat the Action: [Add Identifiers](#add-identifiers)
 
+!!! important "Ask For Help Early"
+    Please if you are having trouble - [ask for help early by clicking on this link](bb-errors.md#help-with-errors){: target="_blank" }.
+
 ## Next Step
 
 The next step is to [Prepare the App](prepare-app.md).

docs/browser/intro-summary.md

@@ -54,7 +54,12 @@
 
 ## 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. 
+The steps to configure for building with a browser require 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.
+
+!!! important "How to Ask for Help"
+    First time setup should take several hours, but if you are having trouble don't get frustrated:
+
+    * [Click here to find help](bb-errors.md#help-with-errors){: target="_blank" }.
 
 ### The Short Version
 

docs/browser/prepare-app.md

@@ -5,6 +5,11 @@ After creating the identifiers, you will need to
 1. [Configure](#configure-identifiers-for-loop){: target="_blank" } them to associate the correct App Group with specific identifiers 
 2. [Create](#create-loop-app-in-app-store-connect){: target="_blank" } the *Loop* App.
 
+Some people get confused on this page. Many of the links look similar but are actually different pages at *Apple*.
+
+!!! important "Ask For Help Early"
+    Please if you are having trouble - [ask for help early by clicking on this link](bb-errors.md#help-with-errors){: target="_blank" }.
+
 ## Configure Identifiers for Loop
 
 ???+ tip "Background Information (Click to open/close)"