Add new items to FAQ. Cleanup existing structure. (#477)

docs/additional-links/_category_.yml

@@ -0,0 +1,3 @@
+label: "Additional links"
+collapsible: true
+collapsed: true

docs/additional-links/local-enrollment.md

@@ -1,4 +1,8 @@
-# Local configuration for natural enrollments
+---
+id: local-enrollment
+title: Local configuration for natural enrollments
+slug: /local-enrollment
+---
 
 ## Desktop
 Preferences to set in Firefox

docs/additional-links/system-architecture.mdx

@@ -1,27 +1,41 @@
+---
+id: system-architecture
+slug: /system-architecture
+---
+
 # System architecture / components
-![image](https://user-images.githubusercontent.com/8192232/211682494-7539f5e5-fc2e-43e1-bd82-db151a1906f7.png)
+<img style={{border:"1px solid grey"}} title="Nimbus system architecture" src="/img/faq/nimbus-system-architecture.png"/>
 [original lives here](https://miro.com/app/board/uXjVOkkueZY=/)
+
 ## Experiment Configuration
+
 ### Experimenter (AKA Nimbus Console)
 This is the interface used by experiment owners and reviewers to capture details about the experiments and the specifics about how to launch it.  
 This is the interface to start, end enrollment, end, and look at results. 
 [stage](https://stage.experimenter.nonprod.dataops.mozgcp.net/) and [production](https://experimenter.services.mozilla.com/nimbus/)
+
 ### Remote Settings
 This is a shared service at Mozilla - that is used to remotely configure the clients. 
 This is the means of applying experiment changes to the client off-train.
+
 ## Client Side
+
 ### SDK
 Each of the Firefox platforms has an SDK that handles all the experiment operations of targeting, enrolling, bucketing, etc.  
 The SDK talks to Remote Settings to get the experiment configurations and changes.
+
 ### Telemetry
 The SDK also generates telemetry on the clients participation in the experiment (state of enrollment, branch, unenrolls).  
 This and the client telemetry use the applications existing Glean or Legacy Telemetry pipeline.
+
 ## Analysis
+
 ### Automated Analysis System (AKA Jetstream)
 Jetstream runs nightly to automatically analyze the metrics for experiments.  
 It runs some metrics for every experiment (varies by platform) and can run additional metrics if there are custom configuration files applied to the experiment.
+
 ### Custom Configuration (AKA Jetstream Configuration Files)  
 A data scientist can write a custom configuration file named after the slug of the experiment to add metrics to an experiment.
+
 ### Analysis library (MozAnalysis)
-Only interfaced with through the data team - this is a repository of vetted metric formulas that can be applied when needed by Data Scientists.
-### 
+Only interfaced with through the data team - this is a repository of vetted metric formulas that can be applied when needed by Data Scientists.

docs/deep-dives/desktop/desktop-pref-experiments.md

@@ -1,11 +1,9 @@
 ---
 id: desktop-pref-experiments
-title: Desktop Pref Experiments
+title: Running Pref-setting Experiments on Desktop
 slug: /desktop-pref-experiments
 ---
 
-# Running Pref-setting Experiments on Desktop
-
 As of Firefox 107, Nimbus supports experiments that set preferences on Desktop.
 Unlike Normandy, Nimbus cannot set arbitrary preferences; instead, the
 preferences that may be set are determined by the feature manifest.

docs/faq/custom-configs/_category_.yml

@@ -0,0 +1,3 @@
+label: "Custom configs"
+collapsible: true
+collapsed: true

docs/faq/custom-configs/custom-configs.mdx

@@ -0,0 +1,11 @@
+---
+id: custom-configs 
+title: Custom configs 
+slug: /faq/custom-configs
+---
+
+### Question
+If I create a custom config for an experiment, will I still results still be generated for the primary and secondary outcomes, if I select them? Or will the config completely overwrite those outcomes?
+
+### Answer
+You will still get the outcomes even with a custom config.

docs/faq/desktop/_category_.yml

@@ -0,0 +1,3 @@
+label: "Desktop"
+collapsible: true
+collapsed: true

docs/faq/desktop/desktop-prefs.mdx

@@ -0,0 +1,15 @@
+---
+id: desktop-prefs
+title: Desktop prefs
+slug: /desktop/desktop-prefs
+---
+
+:::tip
+See the [deep dive on desktop prefs](/desktop-pref-experiments) for more information
+:::
+
+### Question
+We were looking to run an experiment in v115 that required setting a pref. We have registered the pref and landed it on beta, but uplifting to release so late may be problematic. Is there any way to make this experiment work in 115 without that update to FeatureManifest.yaml landing?
+
+### Answer
+No, the only way to set prefs currently requires them to be registered in the feature manifest.

docs/faq/desktop/exposure.mdx

@@ -0,0 +1,17 @@
+---
+id: exposure
+title: Exposure
+slug: /desktop/exposure
+---
+
+:::tip
+See the [deep dive on growable collections](/cookbook/fml/growable-collections#exposure-events) and [Jetstream enrollment vs. exposure](/jetstream/jetstream/#enrollment-vs-exposure) for more information
+:::
+
+### Question
+How do I decide whether I want `hasExposure` to be `true`/`false` on desktop? What's the value of these events or the cases where I might/might not want to use them?
+
+### Answer
+Exposure events are most valuable when a good proportion of enrolled users won’t see the treatment. For example, if seeing the treatment relies on a user action like opening a PDF or using picture in picture.
+
+Sometimes an experiment might have a large impact on the set of users who saw it, but relatively few users did the action to see the treatment. So the “overall” impact of the experiment might be small, but with exposure events we can see that there was indeed a large impact on users who saw the treatment.

docs/faq/early-startup/What-do-it-do.mdx

@@ -1,7 +1,7 @@
 ---
 id: what-do-it-do
 title: What does early startup do?
-slug: /what-do-it-do
+slug: /early-startup/what-do-it-do
 ---
 
 :::tip

docs/faq/early-startup/_category_.yml

@@ -0,0 +1,3 @@
+label: "Early startup"
+collapsible: true
+collapsed: true

docs/faq/early-startup/how-early-is-early.mdx

@@ -1,7 +1,7 @@
 ---
 id: how-early
 title: How early is early?
-slug: /how-early
+slug: /early-startup/how-early
 ---
 
 ## Early on Desktop

docs/faq/end-experiment-behavior/_category_.yml

@@ -0,0 +1,3 @@
+label: "End experiment behavior"
+collapsible: true
+collapsed: true

docs/faq/end-experiment-behavior/ending.mdx

@@ -1,7 +1,7 @@
 ---
 id: experiment-end
 title: What happens at experiment end? 
-slug: /experiment-end
+slug: /end-experiment-behavior/experiment-end
 ---
 
 :::tip

docs/faq/enrollment/_category_.yml

@@ -0,0 +1,3 @@
+label: "Enrollment"
+collapsible: true
+collapsed: true

docs/faq/enrollment/re-enrollment.mdx

@@ -1,7 +1,7 @@
 ---
 id: re-enrollment
 title: Re-enrolled in the same experiment?
-slug: /re-enrollment
+slug: /enrollment/re-enrollment
 ---
 
 ### Question

docs/faq/feature-requires-restart/_category_.yml

@@ -0,0 +1,3 @@
+label: "Feature restart"
+collapsible: true
+collapsed: true

docs/faq/feature-requires-restart/how-to-restart.mdx

@@ -1,7 +1,7 @@
 ---
 id: how-to-restart 
 title: Is this supported?
-slug: /how-to-restart
+slug: /feature-requires-restart/how-to-restart
 ---
 
 This is how it works when a feature requires a restart:

docs/faq/metric-availability/_category_.yml

@@ -0,0 +1,3 @@
+label: "Metric availability"
+collapsible: true
+collapsed: true

docs/faq/metric-availability/non-guardrail-outcome.mdx

@@ -1,7 +1,7 @@
 ---
 id: feature-metrics
 title: Feature metrics aren't there?
-slug: /feature-metrics
+slug: /metric-availability/feature-metrics
 ---
 
 :::tip

docs/faq/mobile/_category_.yml

@@ -0,0 +1,3 @@
+label: "Mobile"
+collapsible: true
+collapsed: true

docs/faq/mobile/mobile-how-to.mdx

@@ -0,0 +1,13 @@
+---
+id: mobile-how-to
+title: Mobile How-To's
+slug: /mobile/mobile-how-to
+---
+
+### Question
+As a mobile engineer, how do I add a dot release version?
+
+### Answer
+* Add a new `Version` to the [constants.py file](https://github.com/mozilla/experimenter/blob/main/experimenter/experimenter/experiments/constants.py) in Experimenter 
+* Run `make generate_types` to generate the new version in `schema.graphql` and `globalTypes.ts`
+* [Example PR](https://github.com/mozilla/experimenter/pull/8870/files)

docs/faq/rollouts/_category_.yml

@@ -0,0 +1,3 @@
+label: "Rollouts"
+collapsible: true
+collapsed: true

docs/faq/rollouts/duplicate-warning.mdx

@@ -0,0 +1,22 @@
+---
+id: rollouts-bucketing-warning
+title: Rollout bucketing warning
+slug: /rollouts/rollouts-bucketing-warning
+---
+
+:::tip
+See the [Rollout FAQ](/deep-dives/experimenter/rollouts) for general rollout information
+:::
+
+### Question
+What does this warning mean?
+
+<p/>
+   <img title="Duplicate bucket warning" src="/img/faq/dupe-rollout-warning.png" align="center"/>
+
+### Answer
+If you are using the [multiple-rollout approach](/deep-dives/experimenter/rollouts#without-using-live-editability), this warning can be safely ignored because you are explicitly creating more than one rollout in the same bucket. 
+
+However, if you are using [live editability for rollouts](/deep-dives/experimenter/rollouts#live-editability), this warning tells you that there is a rollout that is **already live** that has the same application, channel, feature, and advanced targeting as the rollout that you are creating. This means that there will be collision, and your rollout will not function as-is. Users are already enrolled in the live rollout with the same criteria, and they will not be able to enroll in your rollout.
+
+If you are encountering this and you would still like to proceed with your rollout, feel free to reach out to us in [#ask-experimenter](https://mozilla.slack.com/archives/CF94YGE03) on Slack  and we will be able to provide more guidance.

docs/faq/rollouts/rollouts-and-experiments.mdx

@@ -1,7 +1,7 @@
 ---
 id: rollouts-and-experiments 
 title: Rollouts and Experiment Interaction 
-slug: /rollouts-and-experiments
+slug: /rollouts/rollouts-and-experiments
 ---
 
 :::tip
@@ -33,12 +33,9 @@ If they’re focused on different fields of the JSON, the behavior the clients g
 ----
 
 ### Question
-What does this warning mean?
-
-<p/>
-   <img title="Duplicate bucket warning" src="/img/faq/dupe-rollout-warning.png" align="center"/>
+I have a feature that is now on by default in v115, and I want to wait until it has saturated the user base before shutting off the rollout. Do we have a standard around how long we should keep a rollout going in a situation like this?
 
 ### Answer
-If you are using the [multiple-rollout approach](/deep-dives/experimenter/rollouts#without-using-live-editability), this warning can be safely ignored because you are explicitly creating more than one rollout in the same bucket. However, if you are using [live editability for rollouts](/deep-dives/experimenter/rollouts#live-editability), this warning tells you that there is a rollout that is **already live** that has the same application, channel, feature, and advanced targeting as the rollout that you are creating. This means that there will be collision, and your rollout will not function as-is. Users are already enrolled in the live rollout with the same criteria, and they will not be able to enroll in your rollout.
+We typically wait 1-3 releases for the upgrade tail to catch up. You'll probably have the vast majority, so it just depends on the ramifications if people have it enabled on 114 and then lose it.
 
-If you are encountering this and you would still like to proceed with your rollout, feel free to reach out to us in [#ask-experimenter](https://mozilla.slack.com/archives/CF94YGE03) on Slack  and we will be able to provide more guidance.
+If it's **not** a big deal, turn off the rollout in 116 and most people will have it and the stragglers will get it when they upgrade.  If it **is** a big deal - turn off in 117 or 118 and you'll have reached a few percent more with each release.

docs/faq/rollouts/saturation.mdx

@@ -0,0 +1,17 @@
+---
+id: saturation
+title: Rollout feature saturation
+slug: /rollouts/saturation
+---
+
+:::tip
+See the [Rollout FAQ](/deep-dives/experimenter/rollouts) for general rollout information
+:::
+
+### Question
+I have a feature that is now **on by default** in v115, and I want to wait until it has saturated the user base before shutting off the rollout. Do we have a standard around how long we should keep a rollout going in a situation like this?
+
+### Answer
+**Yes**, we typically wait 1-3 releases for the upgrade tail to catch up. You'll probably have the vast majority, so it just depends on the ramifications if people have it enabled on 114 and then lose it.
+
+If it's **not** a big deal, turn off the rollout in 116 and most people will have it and the stragglers will get it when they upgrade.  If it **is** a big deal - turn off in 117 or 118 and you'll have reached a few percent more with each release.

docs/faq/targeting/Targeting.mdx

@@ -1,16 +0,0 @@
----
-id: targeting
-title: Targeting dot releases or specific betas
-slug: /targeting
----
-
-### Question
-Can Nimbus experiments/rollouts target specific beta releases, 
-ie can I express "roll this out to everyone on 104b6 and later"?*
-
-### Answer
-**Yes.** File an issue [here](https://github.com/mozilla/experimenter/issues/new) to add a specific version (of beta, nightly, or release) and then ping in [`#ask-experimenter`](https://mozilla.slack.com/archives/CF94YGE03) on Slack.  
-
-
-The version requested will get added as an option to the Minimum Version and Maximum Version drop down menues. It is a minor and quick change. By default Experimenter (Nimbus) only exposes the whole valued versions, until requested.  
-

docs/faq/targeting/_category_.yml

@@ -0,0 +1,3 @@
+label: "Targeting"
+collapsible: true
+collapsed: true

docs/faq/targeting/advanced-targeting.mdx

@@ -0,0 +1,26 @@
+---
+id: advanced-targeting
+title: Advanced targeting
+slug: /targeting/advanced-targeting
+---
+
+### Question
+How can I add a new advanced targeting option for experiment audiences?
+
+### Answer
+To add new advanced targeting you can open a PR against the [`constants.py` file](https://github.com/mozilla/experimenter/blob/main/experimenter/experimenter/targeting/constants.py) in Experimenter. All that’s needed is to add a new `NimbusTargetingConfig` object, e.g.:
+
+```python
+NEW_ANDROID_13_USERS = NimbusTargetingConfig(
+    name="New Android 13 Users",
+    slug="new_android_13_users",
+    description="Users who have Android 13 and are on their first run of the application",
+    targeting="(android_sdk_version|versionCompare('33') >= 0) && is_first_run",
+    desktop_telemetry="",
+    sticky_required=True,
+    is_first_run_required=True,
+    application_choice_names=(Application.FENIX.name,),
+)
+```
+
+If you need help writing the targeting expression, let us know in [`#ask-experimenter`](https://mozilla.slack.com/archives/CF94YGE03) on Slack.

docs/faq/targeting/version-targeting.mdx

@@ -0,0 +1,18 @@
+---
+id: version-targeting
+title: Targeting dot releases or specific betas
+slug: /targeting/version-targeting
+---
+
+### Question
+Can Nimbus experiments/rollouts target specific beta releases, i.e. can I express "roll this out to everyone on 104b6 and later"?
+
+### Answer
+**Yes.** 
+
+If you are a mobile engineer, see steps [here](/mobile/mobile-how-to) for how to add a version.
+
+Otherwise, file an issue [here](https://github.com/mozilla/experimenter/issues/new) to add a specific version (of beta, nightly, or release) and then ping in [`#ask-experimenter`](https://mozilla.slack.com/archives/CF94YGE03) on Slack.
+
+The version requested will get added as an option to the Minimum Version and Maximum Version drop down menues. It is a minor and quick change. By default Experimenter (Nimbus) only exposes the whole valued versions, until requested.  
+

sidebars.js

@@ -166,71 +166,14 @@ module.exports = {
       ]
     },
     {
-      type: "category",
-      label: "Frequently Asked Questions",
-      items: [
-	{
-          "type": "category",
-          "label": "Early Startup",
-          "items": [
-            {
-              type: 'autogenerated',
-              dirName: "faq/early-startup",
-             }
-          ]
-        },
-	{
-          "type": "category",
-          "label": "End Experiment Behavior",
-          "items": [
-            {
-              type: 'autogenerated',
-              dirName: "faq/end-experiment-behavior",
-             }
-          ]
-        },
+      "type": "category",
+      "label": "FAQ",
+      "items": [
         {
-          "type": "category",
-          "label": "Feature Requires Restart",
-          "items": [
-            {
-              type: 'autogenerated',
-              dirName: "faq/feature-requires-restart",
-             }
-          ]
-        },
-	{
-          "type": "category",
-          "label": "Metric Availability",
-          "items": [
-            {
-              type: 'autogenerated',
-              dirName: "faq/metric-availability",
-             }
-          ]
-        },
-	"faq/rollouts-and-experiments",
-	{
-          "type": "category",
-          "label": "Targeting",
-          "items": [
-            {
-              type: 'autogenerated',
-              dirName: "faq/targeting",
-             }
-          ]
-        },
-        {
-          "type": "category",
-          "label": "Unenrollment",
-          "items": [
-            {
-              type: 'autogenerated',
-              dirName: "faq/unenrollment",
-             }
-          ]
-        },
-      ],
+          type: 'autogenerated',
+          dirName: "faq",
+         }
+      ]
     },
     {
       "type": "doc",
@@ -241,8 +184,10 @@ module.exports = {
       type: "category",
       label: "Additional Links",
       items: [
-        "integration-tests",
-        "local-enrollment",
+        {
+          type: 'autogenerated',
+          dirName: "additional-links",
+         },
         {
           type: "link",
           label: "Experimenter GH Repo",