The Content Editor’s Missing Manual

A few months ago I wrote about how to train content contributors, this article is a little different. It’s meant to be a resource you can point anyone publishing content to the web. The goal is to explain why the web acts different than Word, a general outline of creating semantic documents and how to be a good web content citizen. I get asked this all the time while training new content contributors and thought it would be a good time to actually document it.

The structure of a web page matters

It’s not just about making the page look pretty but the actual HTML behind the page has meaning. The initial thought when charged with updating or maintaining a web page is to initially write up the content in Word, get everything finalized, approved and then copy and paste it into the content management system (CMS). This is a great process but a lot may get lost in the translation from Word to HTML.

It’s all about context

The web is comprised of a collection of individual pages, these pages are linked together and the way visitors get from page to page makes up the users experience. The user experience of your site is not interacting with just a single web page but when they visit dozens if not hundreds each time they set out to accomplish a task. Moving from page to page on your site the visitor is presented with not only the primary content for that page but also the supplemental information surrounding the content. This gives the visitor motivation as they click on links and confidence they are going to eventually end up at the right spot. Writing content without this context is like writing in a white box. You don’t know what else the visitor has seen or is seeing while they are reading your page and can miss some great opportunities to motivate them. With that context though you can make some smart decisions about how long, short, prominent or urgent your copy is. Drafting your page in the CMS and previewing as you go is the more appropriate way to author web content.

Quality of HTML structure matter

While drafting your page in a CMS you will notice hitting Enter will probably create some space between the current sentence and the next, this defines where one paragraph ends and starts. Already the HTML behind your writing will start to describe the structure of your page. The paragraph <p> tag shows there is a separation in ideas from one block of sentences from the next. It is not merely just a way to add spacing in your document.

The next think you would probably do is group these paragraphs under specific topics, just like the larger text in this post. These are called headings. In HTML there are six levels of headings <h1> - <h6>. The central idea of your page should be at the top and marked up with an <h1> (the most important heading) tag then each idea below that should be marked up with the next level heading. Titles within the same idea can have the same level designation so you are not limited to only using it once on your page. This creates a hiarchy of nested topics on a single page. It relates paragraphs to titles and titles to their larger ideas. Think of it like a table of contents in a book, chapters then topics then sub topics then paragraphs.

Underlining isn’t emphasis

Beyond the base structure of your page you may want to call attention to certain sentences or words. Underlining is not an appropriate way to do this on the web. Generally underlines mean the text is a link to another page. Often visitors will try to click on underlined text thinking they are links, especially if they can’t find what they are looking for. If it doesn’t click through they might end up even more frustrated. The preferred way to add emphasis is to make something italic or bold. In HTML it will be denoted as <em> for “emphasis” or <strong> to stand out. This describes your desire to make this text stand out. Where a <u> (underline) tag would not, it just describes the style of the text.

Click here

Eye tracking studies have shown when a visitor is scanning a page they are initially looking for heading, bold items and underlined links. Imagine you land on a page with good heading and structure but every link just says “Click here”. You would have to actually read the sentence before to figure out what you will actually get when you click here. The better option is to link the most descriptive words in the sentence to to the document or page behind it. That way when a visitor scans a page the links are called out and they have appropriate context around them without additional reading.


Without images the web would be boring, it would look like never ending encyclopedia pages. Adding images to the content of your page not only breaks it up but is often necessary to display certain information. On the web each image is actually a separate document and your page just references the location of that image and is pulled in separately.  Making sure the image is resized before uploading it is important. I’m not going to go into a deep discussion about image optimization on the web except to say images that are resized before had to fit the needs of the page not only load faster but are also crisper.


CMS’s get a bad name because they restrict the content creator to just a small portion of the page and basically sandbox the style of that section from all available style sheet definitions for the site. I bring this up because all too often if you want to have publish an image on the right side of the page with a caption it is easy to revert to a table to position and format the image. It works but this is not the point of an HTML table. Tables are meant for tabular data with rows, columns and headers. This is a sticky issue because it takes coordination between the web team and the content contributors to get the appropriate styles in place for the images and captions.

When it doubt, keep it simple

As you add content to a page and it starts to get complicated try breaking the page into multiple. You website visitors don’t care how complicated your page is, they care about finding the information they need. Most importantly of all your pages must be scannable, it doesn’t matter if they have to scroll, visitors scroll. Using the basic elements above is the simplest way to make clear, concise and usable web pages. Your visitors will thank you.

9 Responses to “The Content Editor’s Missing Manual”

  1. Says:

    This post reminds me of something I read recently comparing the nature of the print medium vs web.

    Short doesn’t mean shallow:
    “And now our diagram looks like the web actually looks, lots of pages from different people about different aspects of a very complex world. That is the medium we write in, not some simulation of a stack of paper, no matter what your word processor shows you.

  2. Says:

    I’m so glad you gave me some additional amo to use when explaining why editors shouldn’t use “click here”. I’d previously been using “search engines like incoming/outgoing links” rationale but the eye tracking study reference will probably be much more meaningful.

    When I explain why/when editors should include images, I explain that they should reinforce the actual messaging on the page, not just because it will look pretty. After all, they are content editors, not designers.

    And one last thing; removing the underline button from our WYSIWYG was the single most satisfying day of my career as a higher ed web professional. I think you should all give it a try! :)

  3. Says:

    We don’t have a CMS yet, and maybe we never will. But we’ve got an official blog on Blogger and we’re working on getting a blog server with WordPress 3 up and running. I’ve been thinking about putting together some quick and dirty training or a reference document for faculty, staff, and student bloggers covering the basics of semantic markup and a dozen or so common tags just in case they ever want or need to debug the auto-generated markup. If I ever get around to that, I’ll link here as a “For further reading” sort of thing.

    Thanks for all you contribute to the EDU web community.

  4. Says:

    Nick, Great points - here is a checklist I use in my training classes that has a few more items in it that you may want to include in your manual.

    - Keep copy brief and to the point.
    - Write clearly.
    - Break difficult concepts down into smaller chunks of information.
    - When spelling out steps in a process, use numbered paragraphs
    - When listing items, create a bulleted list rather than putting the items into paragraph format.
    - Use headings throughout your copy to give users visual cues as to the content in each section of a document. This is also extremely important for people who use screen readers to view the page.
    - Spell check your copy.
    - Follow college style guidelines.
    - Use tables for tabular data.

    • Says:

      These are excellent points, Chris. I also encourage my editors to consider the action steps they want the audience to take.

      • Says:

        That’s a great one. I’ll be adding it to my training.

  5. Says:

    Hi Chris,

    You have raised some great pointers. Click Here is something that a lot of webmasters tend to still do. I definitely avoid using them and always anchor the keyword I want especially with article submissions. But a lot of webmasters treat Click here as a call to action, and hence still uses them heavily.

    - Louis


  1. Content Editing Help: Part of the Manual --> says:

    [...] The Content Editor’s Missing Manual [...]

  2. --> says:

    [...] This post was mentioned on Twitter by .eduGuru, eduGuru. eduGuru said: RT @eduGuru The Content Editor’s Missing Manual: A few months ago I wrote about how to train content contrib… [...]