Best Practices for Wiki Content

Best practices:

  • Use header styles for page organization, not for text formatting.
  • Use the basic built in styles and tools to keep your content simple.
  • Keep use of data tables to a minimum. Do not use tables for layout.
  • Links should be contextual. Avoid using "Read More" and "Click Here."
  • Many available macros have not yet been tested for compliance. We recommend keeping your macro use to a minimum.

Properly nest all headings in descending order.

  • The page title is considered a H1 heading, so the first heading created for the page should be a H2. Note: There should only be one H1 on the page.
  • When nesting headings, remember not to skip levels when creating sub-sections. For example, a H2 heading can be followed by a H3, but not a H4.
  • Don’t use the heading format solely for aesthetic purposes. To call out an important point, consider making that sentence bold instead of incorrectly applying a heading format.
Use the built-in heading styles to organize your page elements.

Here are examples of the heading styles in NYU Wikis:

Example of header styles in NYU Wikis

Add alternative text to uploaded images and infographics.

When uploading your image, add alternative (alt) text by selecting the Properties button on the Image Properties panel:

Example of NYU Wikis image settings bar

Select the option for Title, then Alt text.

Example of NYU Wikis Image Properties panel

Provide useful alt text descriptions.
  • When writing your alt text, be concise and consider the purpose your image plays in the context of your content.
  • Because of character limits on different screen reader software, try to keep your alt text fewer than 140 characters.
Avoid using images with text
  • Screen readers are not able to read text displayed within an image.
  • Images with text are difficult to read on smaller screens and can appear pixelated when magnified.
Review your infographics
  • Infographics must include a full text description, located in the main body of your page.
  • Note in your alt text where site visitors can locate the full text description.
  • Some colors are inaccessible to users with color blindness, so do not rely on color alone to convey messages in graphics.

Make sure information and text are clear and easy to read and understand.

  • Keep your content simple and use plain language.
  • Write for your audience
  • Organize the information
To ensure that text is easy to read:
  • Don't underline words, use italics or write in CAPITALS
  • Don't use complicated words or figures of speech
Check that the layout is easy to follow:
  • Avoid large blocks of text:
    Large paragraphs of text can be hard to follow. Use left-aligned text with a short line width and don’t justify text, because it can be more difficult to read extra space between words.
  • Avoid using "Returns" to add space:
    Repeated use of the 'return' key to create white space is not recommended. If somebody was using a screen reader, the returns would be read to them as 'click' 'click' 'click'; or 'space' 'space' 'space'; or 'blank' 'blank' 'blank', depending on their settings. If you need to create space in the document, use headers to set your paragraphs apart.
Linking to other pages or resources:
  • If your content links to a page that you manage which features videos, photos, or audio, include as much descriptive text as possible in your content so users have an idea of what to expect upon arrival. Also make sure that the page to which you are sending users includes content that has descriptive text, captions, or any other description that can help a user understand the page content.
  • If you do not manage the content on the page to which you are linking and the content is not accessible, inform the user first by including a short note of what to expect. For example:
    • A video does not have captions or descriptive text
    • The video will start automatically
    • There is an audio file, but not a written version