| title | layout |
|---|---|
Template Elements |
article |
Titles usually display on the page as well as inside the HTML <title> tag, for consistency and search engine findability.
Subtitles are handy when you find that your title has gotten too long. Subtitles can be longer and more creative than titles, and they’re good for providing extra context in an easily scannable way.
In unstructured content, introductions vary from catchy attention-grabbers to organized summaries. For structured content, introductions serve a more specific purpose: They let readers know what the page contains and what a reader can expect to find. In structured introductions, avoid extraneous information or marketing speak.
Sections can be made up of a heading plus one or more paragraphs or other elements. Headings aren't always necessary.
The defining characteristic of a section is that it’s a standalone information chunk that can be reused outside of the article or document where it appears.
In our educational content, help articles are usually made up of several independent sections that address an aspect of the process or topic.
Numbered lists, also called ordered lists, are used for writing out the steps of a process or listing items that need to go in a specific order.
They're easiest to read when each item is parallel to the others.
Bulleted lists, also called unordered lists, are used to group items or ideas together. Like numbered lists, they're easiest to read when written to be parallel.
Bulleted lists are a great way to break up paragraph text that has gotten too long or includes important information you don't want readers to miss.
See an example of how replacing paragraphs with lists can improve the usability of content by making it easier for users to scan.
Notes are a way to include supplementary or related details that aren't directly related to your main text.
The visual design of a note plays a huge role in its effectiveness. Banner blindness can cause users to ignore them, so be careful of using too many notes or making them stand out from the text too much.
In technical or educational content, warnings alert users to crucial things to do or consider. They should be used even more sparingly than notes, and only when missing the information could cause really bad consequences for the user.
Although dependent on the design of the page, a sidebar is helpful for providing supplementary links, local navigation, or brief related content.
Content aimed at HTML email designers or developers often provides sample code. Set it off in its own chunk so it's easy to use and separate from the page's code.
Sometimes it's helpful to design this chunk so it can be copy and pasted directly into MailChimp or a WYSIWYG. People who aren’t developers may have trouble cleaning the formatting out of the code.
For an example, try copying and pasting the code from the KB's CSS in HTML Email into the MailChimp app. Toggle to code view, and note that only the code you copied is included.
In the Knowledge Base, the merge tag element includes a tag that is copy/pastable like code, plus a description field.
Glossary entries are ideal for reuse. Make sure to separate the term from the description in a different field or with semantic metadata around them.