guidelines.md

Guidelines

This section describes some guidelines to follow when writing HTML examples. It's split into two sections:

• Formal guidelines cover formal aspects of the example, such as how long it should be.
• Content guidelines cover the actual content of the example: that is, what it should include or exclude.

Sometimes formal and content guidelines are at odds. For example, sometimes writing a useful example means making it longer than the formal guidelines ask. Usually, when this happens, we should prioritize content guidelines.

Formal guidelines

In general: try out your example using npm run start and see what it looks like with a browser window width of 1000px.

• Can the user see the whole example source without having to scroll?

• Is the example source readable?

• Does the source look messed up because of how it's wrapped?

• Does the output fit properly in the output pane?

• Does the layout break at narrower widths?

In particular, see the following guidelines for the HTML source and the output:

HTML source formal guidelines

• Keep the line count short: a maximum of 13 lines if possible. By default the editor will show 13 lines, so if the example is more than that, the user will need to scroll to see the whole thing, and this isn't ideal. It's not always possible to keep to this: if you have to, you can increase the editor size to 22 lines, but don't do this unless you have to.

• Keep line length short: as a rule of thumb, try to keep lines under 64 characters.

• Use 4-space indent

• Use line breaks for readability: keep in mind that at different browser widths longer lines will wrap and this can hurt readability. By including line breaks you can make the example more readable at different browser widths. For example, consider an example like this:

<img class="fit-picture" src="/media/cc0-images/Grapefruit_Slice--332x332.jpg" alt="Grapefruit slice atop a pile of other slices"/>

With a browser window width of 1000 pixels, this will wrap like this:

<img class="fit-picture" src="/media/cc0-images
/Grapefruit_Slice--332x332.jpg" alt="Grapefruit slice atop a pile
of other slices"/>

If we add line breaks after each attribute, the example is much more readable:

<img class="fit-picture"
     src="/media/cc0-images/Grapefruit_Slice--332x332.jpg"
     alt="Grapefruit slice atop a pile of other slices"/>

HTML output formal guidelines

By default and with a browser window width of 1000 pixels, the output pane for the HTML examples is 300 pixels high by 350 pixels wide. At those dimensions, does the example look good? If you make the browser window narrower, does the layout of the example still look OK?

Content guidelines

The basic guideline for the example's content is: as simple as possible while still being illustrative and demonstrating good practice.

Illustrate the main concept

Try to make the example engaging, good-looking, and interesting, and to show some important attributes.

However, illustrate the main concept of the item, not every possible usage of it. Remember: the example is not the documentation. It's appearing in a page of documentation that has the space to go into every detail about all the different options that can be used with the item. You don't need to include them all in the example.

For example, here's an example for the <button> element:

<p><button>Default button</button></p>

<p><button disabled>Disabled button</button></p>

<p>
  <button name="submit" type="submit" value="submit-true">
    Form submit button
  </button>
</p>

<p><button accesskey="a">Button with <u>A</u>ccesskey</button></p>

<p><button class="styled">Fancy styled button</button></p>

This includes 5 different button elements. It's too long. The example should include a single element with some common attributes.

Try out your example with npm run start. Can you immediately see the point of the example, or is the element buried in a wall of source?

Use good practices

Although the example should be simple it should illustrate good practice. For example, <input> element examples should include <label> elements:

<label for="pet-select">Choose a pet:</label>

<select id="pet-select">
    <option value="">--Please choose an option--</option>
    <option value="dog">Dog</option>
    <option value="cat">Cat</option>
    <option value="hamster">Hamster</option>
    <option value="parrot">Parrot</option>
    <option value="spider">Spider</option>
    <option value="goldfish">Goldfish</option>
</select>

This also applies to semantics: for example, the example for <aside> should not just be:

<aside>
    <p>I'm an aside!.</p>
</aside>

This doesn't tell the reader anything about how they should use the element. The element should be shown in a context that shows its semantic purpose. For example, one use for <aside> is for a pull quote, so we might try this:

<p>When cut in half we see they are filled with a pure white substance,
like the inside of a young puff-ball. We learn from Professor Peck that
it is called Calostoma cinnabarinus.</p>

<aside>
    <p>We are not responsible for the names given to plants, but cannot
    help wishing that some might be changed or shortened.</p>
</aside>

<p>Calostoma is a Greek word meaning beautiful mouth, and cinnabarinus
is taken from cinnabaris, which means dragon’s-blood. We are not
responsible for the names given to plants, but cannot help wishing that
some might be changed or shortened.</p>