BC Knowledge Article Style Guide

Below are recommended style and usage guidelines to follow when writing BC Knowledge articles. These aren’t hard-set rules, but try to adhere to these style guidelines whenever possible to add consistency; making it easier for readers.

Article Titles

• Phrase article titles as a question, when possible. Exceptions are titles of formal guides (e.g. CUNY Acceptable Use Policy, Article Style Guide) and proper nouns.
• Make your titles descriptive to make it easier to find when searching. Include keywords that users would likely include in their searches. Phrasing as a question helps.
• Try to limit titles to at most 15 words.
• Don’t include entire solutions in your title.
• Capitalize only the first word in a title and proper nouns. Long stretches of capitalized words feel more like newspaper headlines instead of article titles.

Section Headings

• Use H2 for your section heading and H3 for sub-sections within each section. Most knowledgebase articles should not go deeper than two heading levels. H2 and H3 titles are also used to generate the article’s table of contents links.
• Capitalize the words in a short heading. Only capitalize the first word in longer headers and questions. For example: Article Titles, Top 3 reasons to use your Digital ID card.
  (This is somewhat subjective, so use your best judgment here.)

Lists

• Use soft-breaks (Shift + Enter) when adding screenshots or images within lists. This keeps the indentation consistent for the image. Using a hard break creates a new block for the image; separating the image from the associated content.
• Use ordered lists (numbered lists) for sequences and steps.
• Use unordered lists (bullet points) for non-sequential lists.

Links

• Do not link actual urls. Screen readers will read each character (w-w-w-dot-h-t-t-p-colon…).
• Use contextual links. Avoid Click Here links.
• Do not link whole paragraphs or long sentences. Limit links to a few actionable or contextual words.

Images

• Include “alt” tag meta information for images that include information that is not available in the associated text. This helps screen readers explain the image to visually impaired readers.
• Include only relevant portions of your screen when taking screenshots. For example, don’t include a screenshot of your entire desktop when only a small part of the screen is relevant.
• Annotate complex screenshots when it’s not immediately obvious which part of the screen is relevant to the reader. Review the screenshot tutorials to learn more.
• Use screen recordings or animated GIF’s (when possible) to illustrate multi-step processes. If you’re comfortable creating videos, start with images and learn more about recording your screen.

Blocks

• Use the standard WordPress and Heroic KB blocks when possible — avoid custom HTML, which is harder to maintain as the platform is upgraded. Learn more about the available content blocks.