Fixes #524: Add docs for branches page linting and fml errors (#525)

mozilla · Nov 8, 2023 · df7fff8 · df7fff8
1 parent 5dddfec
commit df7fff8
Show file tree

Hide file tree

Showing 7 changed files with 43 additions and 1 deletion.
diff --git a/docs/deep-dives/experimenter/branches.mdx b/docs/deep-dives/experimenter/branches.mdx
@@ -0,0 +1,31 @@
+---
+id: branches-page-deep-dive
+title: Branches
+slug: branches-page
+---
+
+
+### Feature Manifest Language errors (mobile only)
+
+:::tip
+Want more info on the Feature Manifest Language?
+Check out the documentation [here](/fml-spec)
+:::
+
+For non-desktop applications, the Feature Manifest Language (FML) is used to surface errors when we are configuring our branches. This is particularly helpful for deeply nested features, which can be difficult to configure on the Branches page.
+
+You can see that the save button validation has given us usable FML errors, including the line/col number that the error occurs at:
+
+<img src="/img/deep-dives/deeply-nested-fml-error.png"/>
+
+The FML generates errors based on the **feature** you are using, the **application**, and the **channel**. Changing the channel on your experiment may result in different FML errors, since there may be differences between the feature manifests for each channel.
+
+
+## Desktop
+
+When configuring your branches for a desktop experiment, you will see **autocomplete** as you type, as well as **JSON linting**. FML errors are not present on desktop, since desktop does not use the Feature Manifest Language.
+
+
+<img src="/img/deep-dives/desktop-json-error.png"/>
+
+<img src="/img/deep-dives/branches-autocomplete.png"/>
diff --git a/docs/faq/branches/fml-errors.mdx b/docs/faq/branches/fml-errors.mdx
@@ -0,0 +1,11 @@
+---
+id: fml-errors 
+title: FML Errors
+slug: fml-errors
+---
+
+When creating your experiment, you may come across Feature Manifest errors on the Branches page:
+
+<img src="/img/faq/simple-fml-error.png"/>
+
+These errors are generated by the [Feature Manifest Language](/fml-spec) (FML). Learn more about these errors [here](/deep-dives/experimenter/branches-page).
diff --git a/docs/faq/branches/how-many-branches.mdx b/docs/faq/branches/how-many-branches.mdx
@@ -1,7 +1,7 @@
 ---
 title: How many branches can I have?
 sidebar_label: How many branches? 
-slug: /faq/how-many-branches
+slug: /faq/branches/how-many-branches
 ---
 
 While you might want to try out lots of variations for your experiment - each variation reduces your chance of detecting changes.  We highly recommend running as few variations as possible. *Trying to cram too many changes into one experiment can lead to learning nothing about all branches.*  

diff --git a/static/img/deep-dives/branches-autocomplete.png b/static/img/deep-dives/branches-autocomplete.png
diff --git a/static/img/deep-dives/deeply-nested-fml-error.png b/static/img/deep-dives/deeply-nested-fml-error.png
diff --git a/static/img/deep-dives/desktop-json-error.png b/static/img/deep-dives/desktop-json-error.png
diff --git a/static/img/faq/simple-fml-error.png b/static/img/faq/simple-fml-error.png