Skip to main content

Content Principles

Follow these principles to ensure your web content and documentation are accessible and usable.

Adapted from the 18F Content Guide

Address the user

Address the user as “you” whenever possible to refer to the primary audience for the page or site. If you need to use “member” or “patron”, use it as a descriptor of “you” --“As a member of SWAN, you can…”, “As a SWAN patron, you can..”

Avoid duplication

Duplicate content creates poor search results, confuses people, and damages our credibility. If users find two pieces of content that say different things, they will be more likely to open a ticket, or worse, give up.

Before you write new content:

  • Do a Google search--does the content already exist in SWAN support, or an external site such as the RAILS website or SirsiDynix Support?
  • Ask yourself, “Is SWAN the most authoritative source?” Do we control this information? 
  • For content that already exists, we should either link to the most authoritative source, or trust that our members will find it if it comes up easily in a search.

Sometimes it will make sense to write on the same topic for different audiences (e.g. holds management for patrons vs. library staff).

Be concise

Do the hard work to make it simple. Concise writing is harder to write, but easier to read, than wordy writing. Save our members time, and take the time to edit your writing.

  • Use short sentences of 25 words or fewer. Sentences longer than 25 words are more difficult to understand.
  • Vary sentence length to make your writing more interesting.
  • Don’t let caveats dictate grammar: “You can...” not, “You may be able to...”
  • Use pronouns, base verbs, and active voice, and avoid unnecessary modifiers, e.g. "We updated your configuration," not "The configuration for your library has been updated by SWAN staff."
     

Use plain language

Use plain language that our members understand.

  • If you need to use jargon and acronyms, include context and clear explanations. 
  • Minimize definitions - if you need them, define words as you go and avoid a list of definitions.
  • Use words consistently - see the terms list.
  • Short words are faster to scan than long words. 
  • Active voice is easier to read than passive voice.

Structure the content

People read differently on the web than they read print -- they tend to skim, scan, and read only about 25% of the text on the page.

  • Put the most important information first, in inverted pyramid style.
  • Break up text--use short paragraphs, headings, bullets, and numbered lists.
  • Avoid FAQs. They’re difficult to scan, and they’re usually duplicating content that is (or should be) in other areas of the site.    

Make content web-first

Create your content so it is easier for our members to read and search online, and easier for content authors to maintain over time.

  • PDFs, Word Docs, Excel files, and PowerPoints can’t be read on all devices and often require proprietary software.
  • It is easier to update, link to, and search HTML content.
  • HTML content doesn’t “orphan” the user in a new place -- they still have the site’s menus, navigation, and structure.
  • HTML content is responsive--our members can read it on any device.
  • HTML content can also be printed or saved as PDF.


There are some situations where a non-HTML format is appropriate:

  • Information meant to be downloaded and used in a spreadsheet format, such as statistics
  • Presentation slides for a workshop or meeting

In these cases:

  • Include a last updated date in the document.
  • Include the URL where the document can be downloaded.
  • Avoid using a format that requires specific, proprietary software (e.g. Microsoft Word, PowerPoint, Excel).

Note: Presentation slides are never a substitute for information that should be in HTML. Policies, documentation, and other forms of content should be updated as HTML content before or very shortly after the presentation.

Maintain, refine, & retire

Regularly review and update your content. Take advantage of regularly scheduled content audits, but don’t wait to update your content if new information becomes available or older policies and procedures change.

Review web analytics for:

  • Pages with high and low traffic
  • Pages with high and low reading times
  • Common search terms
  • Common user flows

Review tickets for common issues and questions --this could be a sign new documentation is needed.

Your content may need to be archived or deleted as it becomes outdated or redundant. Be thoughtful about deleting content and plan for URL redirects and other tools to help users that are used to finding that content. When it doubt, it is easier to archive or unpublish than re-create from scratch!

Right content, right place, right time

When you create a new piece of content, consider the best content type and location for it. Always ask:

  • Does this need a new page, or is it better as an addition to another piece of content?
  • Where should it go in the main menu? 
  • What are related areas of the site that should link to the new content?
  • Are there any tags, categories, or other taxonomy items that your content will need?
  • Remember, not everyone searches -- all content needs to be findable by browsing, too.

See Content Types for more guidance on the right place for your content.

Audiences

Audiences we serve, in priority order, include:

  1. Patrons
  2. Member library staff
  3. SWAN board, committee, and user group members
  4. SWAN Staff
  5. Potential members
  6. Peer institutions and consortia