Writing

Notice: This documentation has been deprecated

For new web site development and existing site improvement, please refer to the EBI Visual Framework (v1.1) documentation. All services are expected to use the new framework by February 2017.

Guidance for writing content for web pages, considering tone, audience, message, strucutre. The text we write is called "copy" and comes in three main types:

  • Macro copy - paragraphs of text on pages
  • Micro copy - small areas of text that you find on a user interface or in messages
  • Meta copy - the content of meta tags in pages: keywords and description

Macro copy

Macro copy, sometimes called body copy, means paragraphs of text on pages, e.g. documentation, descriptions, news articles, etc. We've found that you can get great results by following Caroline Jarretts principles from Editing That Works:

  1. Understand context of use
  2. Choose what to say
  3. Slash everything else
  4. Edit sentences
  5. Put into logical order
  6. Demolish walls of words
  7. Choose links
  8. Check consistency
  9. Rest it then test it

Caroline recommends using the principles as a process, from 1 to 9. If you'd like to learn more about how to write and edit text, we recommend the one-day EMBL course, Writing for the Web, taught by Caroline Jarrett. You can find details of the course on the EMBL website.

Micro copy

Micro copy is small areas of text that you find on a user interface or in messages. For example, the labels for form inputs; explanatory text; progress or error messages. This text is frequently written by you, the developer who creates the interface, and it is important that it successfully communicates to the user.

Using a microcopy framework

Micro copy small pieces of text in a user interface; help, error or status messages, etc.

Many pieces of microcopy are generic, in which case, you can follow convention. If you're not sure, however, we recommend that you plan how you write microcopy. Aim to keep in mind the message you want to communicate and who will read it. The following framework should help:

Message for: Who will read this?
To tell them: What do they need to know? What is your message?
So they: What should happen as a result?
Displayed via: Next to a page element? Permanent paragraph of text? Pop-up window? etc.
When: Does something trigger the display of this text?
Tone: Imagine you are addressing a colleague. Be clear but jargon-free.

Based on the Intercom microcopy framework, via @destraynor

Meta copy

Meta copy is the content of meta tags in a page - keywords and description. Ideally, words from your meta copy should be repeated in the macro copy of your page. Apart from being clear, this may help the page ranking in search engines.

Keywords

Think of these as tags that help to categorise the content of a page. Ten or 12 is probably a good maximum number to have.

Description

Keep it brief - just describe what this page is about.