Skip to content

Author Editing Guide

WordPress UI
BACKGROUND

Project Details

Transitioning the TCCS (The Claremont Colleges Services) website to a CMS (content management system) gave staff the opportunity to edit their own content. A happy gift to staff but a potential headache to site administrators—who no longer would have complete editorial and technical control over content and its display—this meant an editing guide was needed for staff author/editors.

Staff needed to know how to use the CMS to format text, as well as best practices for presenting content on the web, including:

  1. Editing text
  2. Understanding HTML document structure and how to create semantic content using the editor
  3. Adding images, video, and other media
  4. Making sure that all of the above would be accessible to users who may require technology other than a typical browser (such as screen readers) to consume content.
Web help document

Sample Text

Staying accessible

We all are responsible for keeping this website accessible. Like the old geek joke about gravity, accessibility is not just a good idea—it’s the law. As in, institutions get sued for putting out web content that is inaccessible to people with severe visual or hearing impairments

Sample Text

Staying accessible

We all are responsible for keeping this website accessible. Like the old geek joke about gravity, accessibility is not just a good idea—it’s the law. As in, institutions get sued for putting out web content that is inaccessible to people with severe visual or hearing impairments

lorem ipsum sample text
FIRST THINGS

Editing Text

Most aspects of text editing involved simply explaining how to use the CMS to perform these tasks; some, however, also required judgement and knowledge of web usability best practices. Linking to other content (either internally within the website or externally) was one such aspect.

DESKTOP version below (this text should be hidden in all versions)

Sample Text

Links

Linking text is easy, though the exact procedure depends upon whether you are linking to a page within your unit’s sub-site, a page on our website outside of your unit, or to an external resource.

Accessibility note: visually impaired visitors using screen readers can choose to browse only links on a page, so link text must make sense apart from the surrounding context. Therefore, non-specific phrases (like “click here” or “more”) and URLs-as-text must be avoided (because URLs sometimes contain alphanumeric strings that tell nothing about the link destination).

Tablet version below

Sample Text

Links

Linking text is easy, though the exact procedure depends upon whether you are linking to a page within your unit’s sub-site, a page on our website outside of your unit, or to an external resource.

Accessibility note: visually impaired visitors using screen readers can choose to browse only links on a page, so link text must make sense apart from the surrounding context. Therefore, non-specific phrases (like “click here” or “more”) and URLs-as-text must be avoided (because URLs sometimes contain alphanumeric strings that tell nothing about the link destination).

Mobile version below

Sample Text

Links

Linking text is easy, though the exact procedure depends upon whether you are linking to a page within your unit’s sub-site, a page on our website outside of your unit, or to an external resource.

Accessibility note: visually impaired visitors using screen readers can choose to browse only links on a page, so link text must make sense apart from the surrounding context. Therefore, non-specific phrases (like “click here” or “more”) and URLs-as-text must be avoided (because URLs sometimes contain alphanumeric strings that tell nothing about the link destination).

WRITING FOR THE WEB

Semantic Text

Staff who now would be authoring and editing content needed tips about structuring text, how to think of the function and not the appearance of what they wrote. Left to their own devices, some staff would create paragraphs and turn them into “headings” by enlarging the text and making it bold; or make paragraphs into “list” items by appending a number to the beginning of each. This is not merely an aesthetic error—users of screen readers need headings and other structural cues to help them grasp content organization.

(If you look at the code for this page you may notice that the “Sample Text” excerpts have “headings” which are not headings at all but rather—gasp!—enlarged and bolded text. There is a method to this malfeasance: because the sample text falls outside of this page’s actual document structure, duplicating its original heading structure would introduce a false hierarchy into this page.)

page structure

Sample Text

Page Structure

A web page is (or at least should be) a structured document.

Structure follows function. If text functions as a heading then it should be a heading, not just a line of bold text. If text functions as a list, it should be a list. And so on.

Accessibility note: Document structure helps visitors who cannot see a browser but use a screen reader instead.

Headings

Think of Word or a similar text editor, and how you create a document outline through the use of headings. Do the same when creating web content.

Headings have a hierarchy, from H1 down to H6 (though you probably won’t use headings other than H2–4 … more on that in a moment). Because headings impart structure, use them based on how they function, not how they look, so don’t skip any. This is how a web page outline should look:

Correct heading structure
Correct heading structure

If you leave out a heading, however, you set up an incomplete page structure:

Broken heading structure
Broken heading structure

Sample Text

Page Structure

A web page is (or at least should be) a structured document.

Structure follows function. If text functions as a heading then it should be a heading, not just a line of bold text. If text functions as a list, it should be a list. And so on.

Accessibility note: Document structure helps visitors who cannot see a browser but use a screen reader instead.

Headings

Think of Word or a similar text editor, and how you create a document outline through the use of headings. Do the same when creating web content.

Headings have a hierarchy, from H1 down to H6 (though you probably won’t use headings other than H2–4 … more on that in a moment). Because headings impart structure, use them based on how they function, not how they look, so don’t skip any. This is how a web page outline should look:

Correct heading structure
Correct heading structure

If you leave out a heading, however, you set up an incomplete page structure:

Broken heading structure
Broken heading structure
images of media types
ADDING MEDIA

Images, Video, and Other Media

Media provides a whole level of content beyond text but it comes with some of the biggest challenges to accessibility. The point to be impressed upon staff was this: just because you can see or hear something doesn’t mean everyone can..

Sample Text

Accessibility Notes

Images, video and other media call for particular attention regarding accessibility. Some visitors won’t be able to see them, and in the case of video some will be able to see video features but not hear them. Accordingly, site content cannot depend upon media which can be consumed only by visitors with normal vision and hearing. Wherever media is included, alternatives must be provided for those who cannot use them.

Images

  • Always provide alt text for images (more on how to do this coming up) so visitors using screen readers can at least know what it is they can’t see.
  • Do not use images of text as a substitute for text.
    • If an image contains a small amount of text, make sure this is included in the image’s alt text.
    • If the image contains more text than reasonably can be included in alt text, or if the text requires structure (headings, lists, etc.) in order to be understood, then it should be text on the web page. an image is not an acceptable conveyance for such information.
Image of text in an image
Don’t do this.

Video and audio

Any embedded video and live audio must be captioned and should have a transcript. There are also quality standards captioning must meet:

Common web accessibility guidelines indicate that captions should be:

  • Synchronized – the text content should appear at approximately the same time that audio would be available
  • Equivalent – content provided in captions should be equivalent to that of the spoken word
  • Accessible – caption content should be readily accessible and available to those who need it

[Source: WebAIM: Captions, Transcripts, and Audio Descriptions]

Sample Text

Accessibility Notes

Images, video and other media call for particular attention regarding accessibility. Some visitors won’t be able to see them, and in the case of video some will be able to see video features but not hear them. Accordingly, site content cannot depend upon media which can be consumed only by visitors with normal vision and hearing. Wherever media is included, alternatives must be provided for those who cannot use them.

Images

  • Always provide alt text for images (more on how to do this coming up) so visitors using screen readers can at least know what it is they can’t see.
  • Do not use images of text as a substitute for text.
    • If an image contains a small amount of text, make sure this is included in the image’s alt text.
    • If the image contains more text than reasonably can be included in alt text, or if the text requires structure (headings, lists, etc.) in order to be understood, then it should be text on the web page. an image is not an acceptable conveyance for such information.
Image of text in an image
Don’t do this.

Video and audio

Any embedded video and live audio must be captioned and should have a transcript. There are also quality standards captioning must meet:

Common web accessibility guidelines indicate that captions should be:

  • Synchronized – the text content should appear at approximately the same time that audio would be available
  • Equivalent – content provided in captions should be equivalent to that of the spoken word
  • Accessible – caption content should be readily accessible and available to those who need it

[Source: WebAIM: Captions, Transcripts, and Audio Descriptions]

CONTACT ME

Want to work together?