Add contributing.md with GH workflow and doc edits/creation details (#8)

README.md

@@ -1,18 +1,23 @@
-## Experimenter Docs
+# ☁️ Documentation Hub for Nimbus & Experimenter Users
 
-This repo is the documentation hub for [Experimenter](https://github.com/mozilla/experimenter).
+Check out the docs at: **https://mozilla.github.io/experimenter-docs/**
 
-## Working on the docs
+## About
 
-Pages are written in Markdown, and can be found under [`/docs`](/docs).
+This repository is the documentation hub for [Experimenter](https://github.com/mozilla/experimenter). Its purpose is to be a single source of truth for and house user, developer, and data documentation.
 
-### Using GitHub
+The site is built using [Docusaurus v2](https://v2.docusaurus.io/) and is automatically deployed from the `main` branch to GitHub Pages using GitHub Actions.
 
-You do not necessarily need to clone or set up this repo locally if you just want to contribute to or change documentation.
+Relevant ADRs:
 
-If you wish to modify an existing page, navigate to its Markdown file and click the "Edit" pencil icon in the top-right of the content. You will be presented with a Markdown editor. Make and commit your changes.
+- [Use Docusaurus + GH Pages for the Nimbus User Doc Hub](https://github.com/mozilla/experimenter/blob/main/app/experimenter/docs/adrs/0005-doc-hub.md)
+- [Location for the new Experiment "Docs Hub" codebase + docs](https://github.com/mozilla/experimenter/blob/main/app/experimenter/docs/adrs/0006-doc-hub-repo.md)
 
-If you wish to add a new page, navigate to the directory where you wish to generate the new page and click the "Add File" button in the top right of the GitHub UI. From there you can create the page, add content, and commit it.
+## Contributing
+
+Pages are written in Markdown and can be found under [`docs/`](/docs).
+
+Check out [the Contributing page on GH pages](https://v2.docusaurus.io/) for helpful Docusaurus and GitHub UI tips to learn how to create a new document, edit an existing one, and/or how to adjust the sidebar. You don't have to check out the repository locally to contribute.
 
 ### Working locally
 
@@ -23,4 +28,4 @@ yarn install
 yarn start
 ```
 
-That should open a new browser window automatically, or you can manually browse to http://localhost:3000/ecosystem-platform/ to view the docs.
+That should open a new browser window automatically, or you can manually browse to http://localhost:3000/experimenter-docs/ to view the docs.

docs/contributing.md

@@ -0,0 +1,229 @@
+---
+id: contributing
+title: Contributing
+slug: /contributing
+---
+
+The Experimenter documentation hub is managed in the [mozilla/experimenter-docs](https://github.com/mozilla/experimenter-docs) repository. You will need a GitHub account to contribute.
+
+This page will walk you through how to edit an existing document or create a new one, how to display docs in the sidebar where desired, and how to make these changes in GitHub.
+
+Documents are written in Markdown (`.md`) files using [GitHub-flavored Markdown syntax](https://github.github.com/gfm/) and are compiled into static web pages. [MDX](https://mdxjs.com/) is also supported, meaning you may embed React components in content as needed. Additionally, Docusaurus offers [admonitions](https://v2.docusaurus.io/docs/markdown-features/admonitions) which can be useful when placing emphasis on pieces of documentation. Refer to Docusaurus [Markdown features](https://v2.docusaurus.io/docs/markdown-features) for more technical information about these Markdown pages.
+
+If you need custom CSS styles, you can edit the `src/css/custom.css` file. Try to use classes when writing MDX with names that will be easy to reuse later.
+
+<div className="flex-lg">
+<div>
+
+**Notifications**
+
+If you would like to subscribe to notifications for this repository, including for when someone requests doc changes with a pull request that you can potentially review and approve, be sure to "Watch" the repository by clicking on the repository's "Notification settings" menu and selecting "All Activity."
+
+Also, see [configuring notifications](https://docs.github.com/en/github/managing-subscriptions-and-notifications-on-github/configuring-notifications) in GitHub.
+
+Alternatively, consider subscribing to this repository in the [GitHub Slack](https://slack.github.com/) app by searching for it under "Apps" inside Slack.
+
+</div>
+   <img src="../img/github-watch.png" alt="GitHub Watch" className="img-xs-right" />
+</div>
+
+## GitHub Workflow
+
+All documentation edits and additions will require a pull request into the `main` branch because merged changes will trigger an automatic deployment, but **fear not if you don't prefer pulling down repositories locally and editing files - you probably don't need to.**[^1]
+
+[^1]: If you'd like to preview your sidebar changes or if you need to preview how a document containing MDX will build, you'll likely want to check into your branch and run `yarn start` to see the changes. Please reach out to the Experimenter team if you need help.
+
+### GitHub UI
+
+If you aren't familiar with using Git via the command line, we recommend using the GitHub user interface to make changes to docs. See [the GitHub UI Docs](https://docs.github.com/en/github/managing-files-in-a-repository/editing-files-in-your-repository) if you need further details than what's provided here.
+
+In the following sections, you'll find corresponding links to the GH UI directly under each section title. If you need to edit a file, you'll click on the "Edit" button:
+
+<img src="../img/edit-this-file.png" alt="edit this file" className="img-sm" />
+
+You'll be brought to the GitHub editor page for that file. If you're creating a new document, you'll see a similar editor.
+
+When you're satisfied with your changes or new document, at the bottom of the page, enter a commit message and optional description. Be sure to have the option "Create a new branch" selected, the name of which can be anything, but **if you also need to make edits to the sidebar**, you'll want to keep the branch name in mind.
+
+<img src="../img/commit-changes.png" alt="Commit changes" className="img-xl" />
+
+Click `Commit changes` and you'll be brought to a pull request view comparing your new branch to `main`. If you don't need to make updates to the sidebar, see the [Pull Request Workflow](#pull-request-workflow) section and click `Create pull request`.
+
+#### Doc Edits + Sidebar Edits
+
+If you also need to make updates to the sidebar, you will follow the GH UI link under "Adding or Modifying Sidebar Links" but replace "main" in the URL with the name of your branch. For example, if the name of your branch is `my-flying-nimbus`, [this would be the link](https://github.com/mozilla/experimenter-docs/edit/my-flying-nimbus/sidebars.js) you'd use to edit that file. Similarly to the instructions above, after you've made the desire changes, enter a commit message and optional description. However, this time, you will select the option **commit directly to the `my-flying-nimbus` branch** instead of creating a new branch.
+
+After committing your changes, you'll be brought back to a pull request view comparing your new branch to `main`. You may need to edit the PR title, but if your files changed look good, click `Create pull request` and see the [Pull Request Workflow](#pull-request-workflow) section.
+
+#### Pull Request Workflow
+
+To make sure your pull request is reviewed, either request a specific reviewer to look at your PR, request the `mozilla/project-nimbus-team`, or ask the team in the #nimbus-project Slack channel to take a look.
+
+Automatic checks will run to ensure the project can build and deploy successfully with your changes and at least one reviewer will need to approve your PR. You may receive feedback or questions on your PR that you can address through editing the file in question locally or in the GH UI. When your PR is approved, you should go back to merge your own pull request in case you may want to make another edit before the pull request is merged or because you may get a non-blocking suggestion. If that happens, you can make the change and then merge the PR or simply merge the PR if you disagree with the comment.
+
+Once your PR is merged, you should see your changes reflected [at the URL this hub is housed at](https://mozilla.github.io/experimenter-docs/) in about 10 minutes.
+
+## Create a New Document
+
+:::note
+
+👉 [Click here to this in the GitHub UI](https://github.com/mozilla/experimenter-docs/new/main/docs) 👈
+
+:::
+
+Let's say you want to create a new document called "My Flying Nimbus" that details how to acquire and guide your very own magical, yellow cloud.
+
+In the [`docs/`](https://github.com/mozilla/experimenter-docs/tree/main/docs) directory, either locally on your machine or through the GitHub UI link above, create your file, `my-flying-nimbus.md`. The name can be whatever you want, but it's a good general rule of thumb to keep the name similar to whatever the doc title will be.
+
+Paste the following doc metadata, or frontmatter as it's referred to in Docusaurus, at the top of the file:
+
+```md
+---
+id: my-flying-nimbus
+title: My Flying Nimbus
+slug: /my-flying-nimbus
+---
+```
+
+With this at the top of the MD file, Docusaurus will automatically make your document available for viewing at the slug `/my-flying-nimbus`. Write your document in MD/X and once you're satisfied with your new document, commit and push your changes to your branch or follow the instructions in the [GitHub UI](#Github-UI) section to commit your changes and put in your pull request.
+
+## Modify an Existing Document
+
+:::note
+
+👉 [Click here to this in the GitHub UI](https://github.com/mozilla/experimenter-docs/tree/main/docs) 👈
+
+:::
+
+Editing an existing doc is easy peasy. Click on the link above and choose the document you want to modify, or alternatively, find the "Edit this page" link at the bottom of any document inside the Doc Hub, and follow the instructions in the [GitHub UI](#Github-UI) section.
+
+Modifying the `title` property at the top of the document will update what the sidebar link displays.
+
+Note that if you change the ID also found at the top of the document, you will also need to update the matching string in `sidebars.js` (it's case-sensitive). See the ["Adding or Modifying Sidebar Links"](#adding-or-modifying-sidebar-links) section for more details as well as [Doc Edits + Sidebar Edits](#doc-edits--sidebar-edits) in the GH UI.
+
+## Add or Modify Sidebar Links
+
+:::note
+
+👉 [Click here to this in the GitHub UI](https://github.com/mozilla/experimenter-docs/blob/main/sidebars.js) 👈
+
+:::
+
+If you'd like to add a new external link, link to a new document, or modify an existing link in the sidebar, you have a few options.
+
+Note that the `id` references in this section are case-sensitive. Also, if you'd like more details than what's provided here, you can check out the [Docusaurus Docs on sidebars](https://v2.docusaurus.io/docs/sidebar).
+
+:::info
+
+Tip: If you just need to update the sidebar label and not the page title (atypical), just add `sidebar_label: Nimbuses Are Sweet` to the frontmatter section at the top of the MD file.
+
+:::
+
+1. Create a new top-level internal link to the doc or modify an existing one
+
+<img src="../img/top-level-link.png" alt="top-level link" className="img-lg" />
+
+To set this up, you'll have to modify the `sidebars.js` file locally or through the GH UI link above - all it needs is the `id` that is set at the top of the MD file. It will look something like this to reflect the screenshot:
+
+```js title="sidebars.js"
+module.exports = {
+  sidebar: [
+    "welcome",
+    "my-flying-nimbus”, // this doc ID is all you need to add!
+    ... // other unrelated sidebar items
+```
+
+---
+
+2. Create a new top-level external link to the doc
+
+<div className="flex-lg">
+<img src="../img/top-level-external-link.png" alt="top-level external link" className="img-sm-left" />
+
+<div>
+
+If you'd like to add a new top-level external link, <code>sidebars.js</code> requires an object expecting <code>type</code>, <code>label</code>, and <code>href</code> that will look something like this to reflect the screenshot:
+
+```js title="sidebars.js"
+module.exports = {
+  sidebar: [
+     "welcome",
+   {
+     type: "link",
+     label: "My Flying Nimbus",
+     href: "https://magicalyellowcloud.com",
+   },
+   ... // other unrelated sidebar items
+```
+
+You'll want to make sure `type` is set to `"link"`.
+
+</div>
+</div>
+
+---
+
+3. Create a new internal link to the doc in an existing or new category
+
+<div className="flex-lg">
+<img src="../img/category-link.png" alt="category link" className="img-sm-left order-2-lg" />
+<div>
+
+In Docusaurusland, sidebar menu items with a down caret are called "categories."
+
+To add your internal page to an existing category, find the category via the `label` item in `sidebars.js` which will match the category text you see displayed in the sidebar (see code below). Find the `items` array for that category and add the doc ID you wish to link internally to.
+
+To add your internal page to a new category, copy and paste the entire object shown below where you'd like it to show up in the sidebar. Edit your label as desired and change `items` to `items: ["my-flying-nimbus"]` with your doc ID.
+
+</div>
+</div>
+
+```js title="sidebars.js"
+module.exports = {
+  sidebar: [
+     ... // other unrelated sidebar items
+    {
+      type: "category",
+      label: "Experiment Owners", // what you're looking for, or creating
+      items: ["experiment-owners-root", "my-flying-nimbus"], // doc ID is in this array
+    },
+    ... // other unrelated sidebar items
+```
+
+---
+
+4. Create a new external link to a doc in an existing or new category
+
+<div className="flex-lg mb-16px">
+<img src="../img/category-external-link.png" alt="category link" className="img-sm-left" />
+<div>
+
+The code changes for this option essentially combine options 2 and 3.
+
+To add your external link to an existing category, find the category via the `label` item in `sidebars.js` which will match the category text you see displayed in the sidebar (see code below). Find the `items` array for that category and add the object shown below (also shown in option 2) to the array.
+
+To add your external link to a new category, copy and paste the entire object shown below where you'd like it to show up in the sidebar. Edit your top-level label as desired, remove `"experiment-owners-root",` from the `items` array, and update the label you'd like to display for the link.
+
+</div>
+</div>
+
+```js title="sidebars.js"
+module.exports = {
+  sidebar: [
+     ... // other unrelated sidebar items
+    {
+      type: "category",
+      label: "Experiment Owners", // what you're looking for, or creating
+      items: ["experiment-owners-root",
+        {
+          type: "link",
+          label: "My Flying Nimbus",
+          href:
+            "https://magicalyellowcloud.com",,
+        },
+      }],
+    },
+    ... // other unrelated sidebar items
+```
+
+---

docs/experimenter-engineers.md

@@ -0,0 +1,7 @@
+---
+id: experimenter-engineers-root
+title: Root Page
+slug: /experimenter-engineers
+---
+
+TODO: Update this page introduce the Experimenter Engineers section of the docs. Or, delete it.

docs/welcome.md

@@ -1,6 +1,7 @@
 ---
 id: welcome
 title: Welcome
+sidebar_label: Intro
 slug: /
 ---
 
@@ -10,6 +11,8 @@ You will find documentation pages linked in the sidebar, and all external links
 
 This website is built using [Docusaurus](https://v2.docusaurus.io/).
 
+Want to edit one of these docs, add a new one, or modify the sidebar? Check out the [Contributing](/contributing) page.
+
 ## Important links
 
 In addition to the links in the sidebar here are some important links to have on hand:
@@ -28,23 +31,3 @@ In addition to the links in the sidebar here are some important links to have on
 [storybook_prod]: https://storage.googleapis.com/mozilla-storybooks-experimenter/index.html
 [rs_prod]: https://settings-writer.prod.mozaws.net/v1/admin/
 [rs_stage]: https://settings-writer.stage.mozaws.net/v1/admin/
-
-## Contributing
-
-This documentation is managed in the [mozilla/experimenter-docs](https://github.com/mozilla/experimenter-docs) repository. Content is written in Markdown files using [GitHub-flavored Markdown syntax](https://github.github.com/gfm/) and compiled into static pages. Refer to Docusaurus [Markdown features](https://v2.docusaurus.io/docs/markdown-features) for more technical information about these Markdown pages.
-
-In order to protect the main deploy branch we are requiring all content changes (editing existing pages and creating new pages) to be reviewed and merged via Pull Request. **All changes merged into the `main` branch will automatically be deployed.**
-
-### Creating new pages
-
-[Click here](https://github.com/mozilla/experimenter-docs/new/main/docs) to start creating a new Markdown file in the repository. Once you've written your content you can can click "Commit Changes" to create a new branch and be presented with the option to open a Pull Request.
-
-:::important
-
-One caveat to adding new pages is that if you want them to show up in the sidebar they must be added to the [sidebars.js](https://github.com/mozilla/experimenter-docs/blob/main/sidebars.js) file. If you are adding a new file using the GitHub UI you must first make sure you have changed to the branch you just created with your new page commit. Then you can use the UI to add your new page to the sidebar and add that commit to the Pull Request.
-
-:::
-
-### Editing pages
-
-You can edit any page in these docs by clicking the "**Edit this page**" link near the bottom. This will take you to the GitHub markdown file for the page, where you can make changes to the content. Once you've finished updating the content you can can click "Commit Changes" to create a new branch and be presented with the option to open a Pull Request.

sidebars.js

@@ -1,6 +1,10 @@
 module.exports = {
   sidebar: [
-    "welcome",
+    {
+      type: "category",
+      label: "Welcome",
+      items: ["welcome", "contributing"],
+    },
     {
       type: "category",
       label: "Process",
@@ -37,6 +41,11 @@ module.exports = {
         },
       ],
     },
+    {
+      type: "category",
+      label: "Experiment Owners",
+      items: ["experiment-owners-root"],
+    },
     {
       type: "category",
       label: "Jetstream",
@@ -51,8 +60,20 @@ module.exports = {
     },
     {
       type: "category",
-      label: "Experiment Owners",
+      label: "Data Scientists",
-      items: ["experiment-owners-root"],
+      items: ["data-scientists-root"],
+    },
+    {
+      type: "category",
+      label: "Experimenter Engineers",
+      items: [
+        "experimenter-engineers-root",
+        {
+          type: "link",
+          label: "GitHub Repo",
+          href: "https://github.com/mozilla/experimenter",
+        },
+      ],
     },
     {
       type: "category",
@@ -86,10 +107,5 @@ module.exports = {
         },
       ],
     },
-    {
-      type: "category",
-      label: "Data Scientists",
-      items: ["data-scientists-root"],
-    },
   ],
 };

src/css/custom.css

@@ -12,6 +12,7 @@
 [data-theme="dark"]:root {
   --ifm-toc-border-color: #373737;
   --ifm-color-primary: #55a7ff;
+  --ifm-hr-border-color: var(--ifm-color-emphasis-300);
 }
 
 .main-wrapper {
@@ -54,3 +55,52 @@
   position: relative;
   margin-left: 10px;
 }
+
+.mb-16px {
+  margin-bottom: 16px;
+}
+
+.img-lg {
+  width: 500px;
+  max-width: 100%;
+}
+
+.img-xl {
+  width: 700px;
+  max-width: 100%;
+}
+
+.img-xs-right {
+  width: 225px;
+  margin-left: 24px;
+}
+
+.img-sm {
+  width: 300px;
+}
+
+.img-sm-right {
+  width: 300px;
+  margin-left: 24px;
+}
+
+.img-sm-left {
+  width: 300px;
+  margin-right: 24px;
+}
+
+.flex-lg {
+  display: flex;
+  flex-direction: column;
+}
+
+/* Docusaurus desktop breakpoint */
+@media screen and (min-width: 997px) {
+  .flex-lg {
+    flex-direction: row;
+    align-items: flex-start; /* prevents vertical img stretch */
+  }
+  .order-2-lg {
+    order: 2;
+  }
+}