Writing documentation

Editing pages

The easiest way to edit a page is with Edit this page on GitHub link that appears at the bottom of every page on the site. The link opens the specific GitHub page where you can edit the content and then propose the change with a pull request.

Alternatively, if you have a specific fix or contribution, you can fork the repo and generate a pull request.

Content and style guidelines

Before you get started, take a moment to review our content guidelines. Following these will help us ensure consistency of experience across the site.

Use Markdown

The website is written in Markdown, which makes it easy for anyone to contribute content in a systematic way. If you don’t already have a Markdown editor installed, there are plenty of free editors available online.

Guidelines for writing content

Aim for a friendly and encouraging tone. Speak directly to the user. You can use the second person pronoun (“you”). Keep sentences and paragraphs short and focused. Be clear and concise by removing unnecessary words. The more concise the text, the easier it is for all users to understand. Use sentence case for everything, including component names, e.g. Content switcher and Data table.

Components

Each file begins with a frontmatter section that contains metadata about the page. The frontmatter section is surrounded by three dashes on either side. The frontmatter section is written in YAML.

---
title: 'Writing the documentation'
subtitle: 'Naming convention & linting'
slug: 'Documentation/Developing/Naming convention'
excerpt: 'Colours for the WFP design system'
coverImage: './components.png'
ogImage:
  url: './components.png'
---

Callout

<Callout title="Note" kind="info">
  If you are a designer working at WFP, please refer to our team to join the WFP
  Figma organization.
</Callout>

Embed Figma

Embed Figma files directly as interactive prototypes. You can also embed specific frames from a Figma file.

<Figma
  url="https://www.figma.com/file/wFEEbUEWrlfMhs2a1S2RTp/UN-core-website?node-id=0%3A1&t=ffaLsECV8p10ZEa4-1"
  height="300"
/>

Embed a specific frame from a Figma file as image (loads faster).

<FigmaImage document="wFEEbUEWrlfMhs2a1S2RTp" node="801:341" />

Copy code

Storybook

Embed a Storybook component directly from the Storybook website. Define the path of the component.

<Storybook path="iframe.html?viewMode=docs&id=components-ui-elements-button--documentation" />;

Do and Don't

Use the DoUse and DoNotUse components to show examples of good and bad practices.

<DoUse>

- Use accordions to organize information
- Use accordions to reduce the amount of scrolling required
- Use accordions to reduce the amount of information displayed on the screen at once

</DoUse>

<DoNotUse>

- Do not use accordions to display information that is not related
- Do not use accordions to display information that is not hierarchical
- Do not use accordions to display information that is not collapsible

</DoNotUse>

Typeset

Embed the different available Typefaces. Only used on the Typography page.

<Typeset />

Code blocks

Use code blocks to show examples of code. You can specify the language of the code block to enable syntax highlighting.

```jsx
<Button>Button</Button>
```;

Live code example

Live code blocks allow you to show a preview of the code. The code is executed and the result is shown below the code block. This will also autoformate the code.

```jsx live

````bash
```jsx live preview
<Button>Button</Button>
```

<Button>Button</Button>;

ReactHookForm example

Use the reactHookForm language to show a live example of a form using the React Hook Form library.

```jsx live reactHookForm
<InputGroup labelText="Input group" helperText="Describing the input group">
  <Checkbox
    id="1"
    name="check-1"
    labelText="Option 1"
    {...register("check-1")}
  />
  <Checkbox
    id="2"
    name="check-2"
    labelText="Option 2"
    {...register("check-2")}
  />
</InputGroup>
```

const FormExample = () => {
  const [defaultValues, setDefaultValues] = useState(
    {}
  );
  const {
    control,
    register,
    handleSubmit,
    watch,
    reset,
  } = useForm({ defaultValues });
  const [data, setData] = useState({});

  const setDefaultValuesFunc = (e) => {
    console.log(e.target.value);
    try {
      const values = JSON.parse(e.target.value);
      setDefaultValues(values);
    } catch (e) {
      console.log(e);
    }
  };

  const resetInputs = () => {
    reset(defaultValues);
  };
  const currentValues = watch();

  return (
    <>
      <form
        onSubmit={handleSubmit((data) =>
          setData(data)
        )}
      >
        <InputGroup
          labelText="Input group"
          helperText="Describing the input group"
        >
          <Checkbox
            id="1"
            name="check-1"
            labelText="Option 1"
            {...register("check-1")}
          />
          <Checkbox
            id="2"
            name="check-2"
            labelText="Option 2"
            {...register("check-2")}
          />
        </InputGroup>
        <Button type="submit">Submit</Button>{" "}
        <Button onClick={resetInputs} kind="secondary">
          Reset here
        </Button>
        <div className="debug">
          <h4>Submitted form data</h4>
          <pre>{JSON.stringify(data, null, 2)}</pre>

          <h4>Current values</h4>
          <pre>
            {JSON.stringify(currentValues, null, 2)}
          </pre>

          <TextInput
            labelText="Default values (editable)"
            defaultValue={JSON.stringify(
              defaultValues
            )}
            onChange={setDefaultValuesFunc}
          />
        </div>
      </form>
    </>
  );
};

render(<FormExample />);

Mobile preview

Use the size attribute (live size="mobile")to show a mobile preview of the code block.

```jsx live size="mobile"
<MainNavigation showLogo logo="Product name">
  <MainNavigationItem>
    <Link href="https://go.docs.wfp.org" target="_blank">
      Section 3
    </Link>
  </MainNavigationItem>
  <MainNavigationItem>
    <Link href="http://opweb.wfp.org" target="_blank">
      Section 4
    </Link>
  </MainNavigationItem>
</MainNavigation>
```

<MainNavigation showLogo logo="Product name">
  <MainNavigationItem>
    <Link
      href="https://go.docs.wfp.org"
      target="_blank"
    >
      Section 3
    </Link>
  </MainNavigationItem>
  <MainNavigationItem>
    <Link href="http://opweb.wfp.org" target="_blank">
      Section 4
    </Link>
  </MainNavigationItem>
</MainNavigation>;

forceFullWidth

Use the forceFullWidth attribute (live forceFullWidth) to force the code block to take the full width of the page.

```jsx live forceFullWidth
import {
  BannerNavigation,
  MainNavigation,
  MainNavigationItem,
} from "@wfp/react";

() => (
  <>
    <BannerNavigation>
      <BannerNavigationItem>
        <Link href="http://communities.wfp.org" target="_blank">
          Communities
        </Link>
      </BannerNavigationItem>
    </BannerNavigation>
    <MainNavigation>
      <MainNavigationItem>
        <Link href="http://communities.wfp.org" target="_blank">
          Section 1
        </Link>
      </MainNavigationItem>
    </MainNavigation>
  </>
);
```

import {
  BannerNavigation,
  MainNavigation,
  MainNavigationItem,
} from "@wfp/react";

() => (
  <>
    <BannerNavigation>
      <BannerNavigationItem>
        <Link
          href="http://communities.wfp.org"
          target="_blank"
        >
          Communities
        </Link>
      </BannerNavigationItem>
    </BannerNavigation>
    <MainNavigation>
      <MainNavigationItem>
        <Link
          href="http://communities.wfp.org"
          target="_blank"
        >
          Section 1
        </Link>
      </MainNavigationItem>
    </MainNavigation>
  </>
);