docs: add "The Anatomy of Unleash" (#2138)

## What

This PR

1. adds a new topic document, "The Anatomy of Unleash", which explains
how Unleash is built up as a system.
2. It also moves the "topic guides" sidebar entry from position 4 to
position 2.
3. Finally, it introduces a new `Figure` component for the
documentation, to be used with images that should be shown with
captions.

## Why

Referring to the same numbers as mentioned above, here's some background
for these changes:

1. We have gotten requests from enterprise users for a way to help new
Unleash users understand the system. Together with customer success and
customer journey, we agreed that an explanatory guide would be suitable.
It aims to give the reader an introduction into what pieces constitute
the Unleash system.
2. As part of a discussion, it was suggested to move topic guides higher
up to make them more visible. There's a few reasons for this:
1. New users of Unleash should be able to keep reading about Unleash
after the basic introductory material. When left at the bottom, topic
guides are often overlooked
2. As a justification, it was proposed that reference docs are often the
last thing you look for, so it makes sense to put that last.
3. Thinking about a new user's flow, it also makes some sense: first
read introductory material, then dive deeper into what Unleash is and
what you can use it for, then look for how-to guides if you're stuck,
and finally consult the reference material for later.
3. These diagrams aren't necessarily very self-explanatory, so adding a
caption makes a lot of sense. We didn't have a component from this
previously, so I added one.

Co-authored-by: NicolaeUnleash <[email protected]>
Co-authored-by: Simon Hornby <[email protected]>

## Commits

* docs: add raw export of anatomy document

* docs: move the topic guides section to near top of sidebar

* docs: add inter-doc links, some reformatting

* docs: fix broken links

* docs: add a Figure element for figures with captions

* docs: add more styling to figures

* docs: align on styles

* Fix: add fuller figure caption

* docs: rephrase heading

* Docs(test): try new way of importing images

* Docs(test): images take 3

* docs: Convert all images to using the figure component

* docs: add projects to list of top-level resources

* docs: add captions for all figures.

* docs: reorder images

* Docs(fix): typo: extra brackets

* Docs(style): remove box shadows and border on fig caption images

* Docs(chore): remove commented-out css

* Docs(refactor): use css variable for small font size.

To facilitate reusability and convey meaning.

* docs: rename anatomy doc

* docs: add note about strategies vs constraints

* Updating the images

* Apply suggestions from code review

Co-authored-by: Simon Hornby <[email protected]>

* Update website/docs/topics/the-anatomy-of-unleash.mdx

* Docs(fix): remove redundant comma

* docs: add link to node js sdk

* docs: mention that a toggle must be active in an env to be enabled

* docs: add note about environments and api keys

* Docs(reword): swap dev and prod in example

* docs: fix typo in the image

* docs: make figures in text full-width

* docs: move environments and API keys call-out to after figure

* docs: add borders to figures

* docs: add image float css idea

* Revert "docs: add image float css idea"

This reverts commit 69f27d3.

Co-authored-by: NicolaeUnleash <[email protected]>
Co-authored-by: Simon Hornby <[email protected]>

Author: 3 people

website/docs/topics/the-anatomy-of-unleash.mdx

@@ -28,6 +28,23 @@ module.exports = {
                 'user_guide/quickstart',
             ],
         },
+        {
+            label: 'Topic guides',
+            collapsed: false,
+            type: 'category',
+            link: {
+                type: 'generated-index',
+                title: 'Topic guides',
+                description:
+                    'Discussions, explanations, and explorations regarding topics related to Unleash.',
+                slug: '/topics',
+            },
+            items: [
+                'topics/the-anatomy-of-unleash',
+                'topics/a-b-testing',
+                'topics/proxy-hosting',
+            ],
+        },
         {
             label: 'How-to guides',
             collapsed: false,
@@ -305,18 +322,5 @@ module.exports = {
                 },
             ],
         },
-        {
-            label: 'Topic guides',
-            collapsed: false,
-            type: 'category',
-            link: {
-                type: 'generated-index',
-                title: 'Topic guides',
-                description:
-                    'Discussions, explanations, and explorations regarding topics related to Unleash.',
-                slug: '/topics',
-            },
-            items: ['topics/a-b-testing', 'topics/proxy-hosting'],
-        },
     ],
 };

website/sidebars.js

@@ -0,0 +1,30 @@
+import React from 'react';
+import Component from './Figure';
+import Layout from '@theme/Layout';
+import { BrowserRouter } from 'react-router-dom';
+
+export default {
+    title: 'Figure',
+    component: Component,
+};
+
+const Template = (args) => (
+    <BrowserRouter>
+        <Layout>
+            <Component {...args} />
+        </Layout>
+    </BrowserRouter>
+);
+
+export const WithCaption = Template.bind({});
+WithCaption.args = {
+    img: '/img/anatomy-of-unleash-constraint.png',
+    caption: 'This explanatory caption is visible to everyone.',
+};
+
+export const WithCaptionAndAlt = Template.bind({});
+WithCaption.args = {
+    img: '/img/anatomy-of-unleash-constraint.png',
+    caption: 'This explanatory caption is visible to everyone.',
+    alt: "This alt text is read out by screen readers and displayed if the image doesn't load",
+};

website/src/components/Figure/Figure.stories.tsx

@@ -0,0 +1,90 @@
+/**
+    This component displays a figure with an accompanying figure caption. Use it
+    to display diagrams, charts, and other images that have an explanatory
+    caption that should be visible to everyone.
+
+    For some info regarding alt text vs fig captions, see this stack overflow
+    response from a blind user (available at
+    https://stackoverflow.com/questions/58447538/accessibility-difference-between-img-alt-and-figcaption):
+
+    I'm a blind user. I would say that there are two big categories of images on the web:
+
+        1. Functional images
+        2. Illustrative images a.k.a. figures
+
+    AS the name says, figcaption is a caption for a figure. The caption is
+    always visible by everybody, not only blind people. Figures are images that
+    can be found in a book, an article, or whatever more or less long paragraphs
+    of text. Most of the time, figures are purely illustrative.
+
+    When you use figcaption, the alt attribute should probably be empty:
+
+    - Copying the text of the figcaption into the alt attribute, or any
+      shortened version, is almost always useless: the screen reader will read
+      twice the same or almost the same information, and it's worth absolutely
+      nothing
+
+    - You may think that the alt attribute could be useful for a longer
+      description of the image, that wouldn't fit in the figcaption; for example
+      a detailed description of a chart or a diagram. But in fact, this kind of
+      description is better below the image or in another page (then available
+      for everybody), rather than in the alt attribute. The alt attribute should
+      normally remain short.
+
+    - You may think that the figcaption is useless and only set the alt
+      attribute to something. Example: "Photo with Alice on the left, Bob on the
+      right". But in fact sighted people could as well find this information
+      useful, if they don't know Alice and Bob for example. So it could be
+      interesting to move this description to the figcaption, so that everybody
+      benefits from it and not only blind people.
+
+    Now, the biggest case when you won't use figure/figcaption is when images
+    are functional: a button taht can be clicked, an icon with a precise
+    meaning, etc. The basic rules for alt texts of functional images are:
+
+    - If you can interact with the image to perform actions (click, etc.), or if
+      the icon conveys an information, then you must set a non-empty alt. It
+      must be a function description, not a objective description of the image.
+
+        Example 1: "Go back" is good, while "Blue left arrow" is bad.
+        Example 2: "Unread message" is good, while "Closed enveloppe" is bad
+
+    - Otherwise, if the image provide no interaction and if it doesn't convey
+      any information, then it is illustrative; the alt should be empty in that
+      case.
+
+      ------
+
+    However, even when using fig captions, there **may** be times when also
+    using an alt is appropriate, which is why it's an optional attribute on
+    this component. However, if you do use it, make sure it conveys
+    **separate** information to what the fig caption does.
+
+
+**/
+
+import React from 'react';
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+import './styles.module.css';
+
+type Props = {
+    // An optional alt text, if the caption does not already convey all relevant
+    // information.
+    alt?: string;
+    // The figure caption, visible to everyone
+    caption: string;
+    // the path to the image, starting with `/img/`. Example: /img/image.png
+    img: string;
+};
+
+const Component: React.FC<Props> = ({ img, alt, caption }) => {
+    return (
+        <figure>
+            <img alt={alt} src={useBaseUrl(img)} />
+            <figcaption>{caption}</figcaption>
+        </figure>
+    );
+};
+
+export default Component;

website/src/components/Figure/Figure.tsx

@@ -0,0 +1,23 @@
+/* Figures (with captions) */
+figure {
+    box-shadow: var(--ifm-global-shadow-lw);
+    border-radius: var(--ifm-global-radius);
+    border: var(--ifm-global-border-width) solid var(--unleash-color-gray);
+    padding: var(--ifm-pre-padding);
+    margin-inline: 0;
+}
+
+figure img {
+    box-shadow: none;
+    border: none;
+}
+
+figure * + * {
+    margin-block-start: var(--ifm-pre-padding);
+}
+
+figcaption {
+    font-size: var(--unleash-font-size-smaller);
+    padding-inline: var(--ifm-pre-padding);
+    border-inline-start: 5px solid var(--ifm-color-primary);
+}

website/src/components/Figure/styles.module.css

@@ -13,6 +13,8 @@
     --ifm-code-font-size: 90%;
     --ifm-font-size-base: 15px;
     --navbar-link-color: #122d33;
+
+    --unleash-font-size-smaller: 90%;
 }
 
 footer {