(alistapart article) Nothing brings content modeling to life like launching a shiny new site: teasers fit neatly without any awkward ellipses, images are cropped perfectly for different screen sizes, related content is wonderfully relevant. The content strategy comes to life, and all is right with the world.
But for years, my joy was short lived—because it would only take a couple weeks for things to begin to fall apart: teasers would stop teasing, an image would get scaled oddly, and—I won’t lie—I’d even start seeing “click here” links.
“Why are you messing this up?” I’d wonder. The content was perfectly modeled. The CMS was carefully built to reflect that model. I even wrote a detailed training document!
In my mind, I saw authors printing out my instructions and lovingly taping them to the side of their screen. In the real world, they skimmed the document once, then never opened it again. When new staff was hired, no one remembered to tell them a content guide even existed.
The problem? I’d spent months neck-deep in the content model, and knew exactly how important those guidelines were. But the authors didn’t. For most of them, it was their first time breaking content into its component parts and building it for reuse. It’s not surprising they were fumbling their way through the CMS: misusing fields, putting formatting where they shouldn’t, and uploading images that clashed with the design.
Maybe you’re like me: you know what needs to happen in the CMS to create the experience everyone’s bought into on the front end, but you’ve found there’s a big difference between having a plan and actually getting people to execute it in their daily work. The results are frustrating and demoralizing—both for you and for the authors you’re trying to help.
Don’t despair. There’s a better way to get your content guidelines adopted in the real world: put them right where they’re needed, in the CMS itself.
Getting the team together
If you’ve made a content template or page table before, the idea of an instructional content strategy document will sound familiar. Content templates act as a guide to a content model, explaining the purpose of each field and section, including information like intended audience, style reminders, and example copy. The problem is that these guidelines typically live independently of the CMS; the closest they ever come to integration is including a few screenshots of the editing interface.
Content guides are generally owned and created by whoever is in charge of content in a team. But actually gathering the guidelines is a collaborative effort: a designer contributes information about ideal photo caption length, art direction, and image sizing. A developer knows all the different places a particular field will be displayed, which file formats are accepted for upload, and how many blog posts can be promoted to the front page at once. A project owner or manager knows whom the author should contact with attribution questions, which audience a product description should target, and which voice and tone documents are relevant for each content type.
Getting content guidelines into the CMS itself requires connecting all these disciplines, which means it doesn’t fit neatly into most teams’ processes. In this article, I’ll show you how to bring all the pieces together to create guidelines that provide help when an author needs it, and make it easier for them to do their job well. We’ll do this by following three principles.
Good labels and guidelines:
- provide context, explaining what a field is for and how it will be used;
- are specific, encouraging accuracy and uniformity while eliminating guesswork; and
- are positive and helpful, rather than hostile and prohibitive.
Let’s walk through how we can apply these principles to each piece of the CMS, using specific examples and addressing common challenges.
Content types
Before throwing an author into the endless fields of an edit form, we want to give them an introduction to the overall content type: what it is, where and how it will be displayed, and who it’s for.
Let’s say authors used to create new pages for each event, and then remove them (when they remembered!) after the event ended. We’re replacing that with a specific Event content type. To help authors transition, I might include text like:
Events are displayed in the Calendar page and in a block on the homepage, and will be automatically archived after their date has passed. The calendar is mainly used by members who are already familiar with our work and internal terms.
Where and how this works varies by CMS. For example, Drupal has an “Explanation or submission guidelines” field for each content type that displays at the top of every entry’s edit page. WordPress allows you to add meta boxes to edit screens with custom code or plugins like Advanced Custom Fields, which makes the information more accessible than hiding it in the contextual help tab. If you’re not sure how to do this in your CMS, talk to your developers—chances are, they can make it possible once they understand the goal.
Field names
When naming fields:
- Be specific and descriptive. For example, in an artist profile, you might replace the default of “Title” and “Body” with “Artist Name” and “Biography.” Even when they feel redundant, field names like “Event Name” and “Event Description” help orient the author and remind them which content belongs where.
- Describe the content in the field, not the format of the field. An image field named “Image” doesn’t tell an author what kind of image. Something like “Featured Photo” is better, and best is a specific description like “Venue or Speaker Photo.”
- Be consistent. For example, don’t phrase a label as a question (“Open to the public?”) unless you consistently use questions across all your fields and content types.
CMS form using three generic field names: Title, Type, and Body. Before: Generic field names on a CMS entry form.
CMS form using three specific field names: Artist Name, Preferred Medium, and Full Biography. After: Specific field names give context to the entry, and help authors avoid mistakes.
Help text and instructions
Where a field name describes what content is, help text describes what it does. The goal is to help authors meet the site’s strategic, format, and style needs, and answer questions like the ones in these four categories:
Messaging and information
- What’s the underlying message of this copy?
- What does this content do, in the context of the site? Is the point of this field to inform a user, drive them to action, or provide metadata for the site structure?
- Are there things this field must include, or shouldn’t include?
- Should the alt text describe, caption, or explain the function of this image?
- Who’s the audience? Are they new to our work or familiar with our internal jargon?
Style, voice, and tone
- What grammatical structure should this text take (e.g., full sentence, sentence fragment, Three. Word. Tagline.)?
- Should the title be straightforward, or written as clickbait? (Hint: NO.)
- Should there be ending punctuation?
- Character count can be enforced by the CMS, but is there an ideal length the author should aim for?
- Are there style rules, such as acronym or capitalization usage, that are likely to come into play?
- Are you trying to change authors’ current writing habits? For example, do they need reminders not to write “click here” or reference page location like “the list to the left”?
Technical
- Which formats are allowed for an image or file upload?
- Do uploads have a size limitation?
- Should the filename follow a specific pattern (e.g., OrpingtonPoster-August2014.pdf)?
- If a field uses HTML, which tags are accepted?
- For a checkbox or select list, is there an upper or lower limit to the number of selections?
Design and display
- Does the value of this field change how or where the content is displayed? For example, does a checkbox control whether an article will be pushed to the homepage?
- Does this field display alongside other fields (and so shouldn’t be duplicative), or appear alone (like teaser text)?
- Will the CMS scale and resize images automatically, or does the author need to upload multiple versions?
- Where will this image be displayed? Will different sizes (like thumbnails) show in different places around the site?
- Are there art-direction requirements for this image? For example, does it need dark negative space in the left for an overlaid headline? Should it show a person looking directly at the camera?
CMS event entry form with specific help text like “Spell out your acronyms!” and “When possible, use place names over street addresses” for each field. A CMS form with a mix of technical and editorial guidelines helps authors create consistent content entries.
Making every word count
You can’t answer all of those questions at once—no one is going to read three paragraphs of instructions for a single text field. Your goal is to highlight the most valuable—and most often forgotten—information. For example, a company that long-ago settled on PNGs for its product images doesn’t need reminders of appropriate file types. You might remind users to write in second person in a “Subtitle” field, then link off to a full voice and tone document for more guidance.
Whatever you do, use space wisely—if the field label is “Featured Photo,” don’t write “This is where you upload the featured photo.”
Special considerations
Beware the big WYSIWYG
Even the most well-meaning authors can be overwhelmed by a big blank box and a million WYSIWYG buttons, and the results aren’t pretty. Editorial guidelines help remind users what these long text fields should and shouldn’t be used for.
If authors will be doing any formatting, it can be helpful to customize the WYSIWYG and provide explicit styling instructions to keep them on track.
WYSIWYG editor with a very limited selection of formatting buttons, and help text including advice like “Remember that date-specific events should be made into Timeline entries rather than tucked into this field.” WYSIWYG field with a limited selection of buttons, including editorial and formatting guidelines.
Be wary of endless “DO NOT” instructions. Positive reminders and examples of good content can be just as effective—and feel much friendlier—than prohibitions.
Making lists contextual and clear
Select fields and lists of checkboxes are part of many content types, but they’re used for a variety of different functions: a “Category” field might control where an entry is shown on the site, how it relates to other content, or even which layout template will be used for display. Good instructions provide authors with this context.
Please remember to change your lowercase, underscore-ridden, concatenated, and abbreviated machine names, like “slvrLc_wynd,” to real words, like “Silver-Laced Wyandotte.” Key:label pairs exist so that your authors don’t have to speak database to be successful. Use them.
Ordering your fields
Many CMSes will let you group fields—most commonly in fieldsets or tabs—to help authors make sense of what they’re seeing. In most CMSes, the front-end display order doesn’t need to match the backend form order, so you can organize fields to help the authors do their job without affecting how things look on the live site.
Usually, you’ll want to either group similar content fields together, or arrange fields in the order they’ll be entered.
For example, say that you need multiple versions of a single piece of information, like a short title and a long title. It’s helpful to see these side by side, with reminders about how specifically the versions should differ from one another.
Or, say that your content will be copied from another system, like a manufacturer’s specification or a legacy database. Matching your field order to the content source means that authors won’t have to skip around while creating an entry. Similarly, if your authors always enter the “Event Location” content in between the “Presenter Bio” and “Event Date” fields, the edit form should match that—even if it’s not the order that makes the most sense to you.
Two fieldsets showing fields organized in groups under Homepage slideshow and Open graph metadata. Fieldsets help make sense of complex CMS entry forms, organizing fields into groups that help authors keep track of different types of content.
Getting specific
The developer in me wants to create a library of reusable generic help snippets, but the best instructions I produce are the ones that are specific to a particular client’s internal organization and processes. Don’t shy away from including information like “Contact Ann Sebright (x8453) for photo attribution information,” or “Check the internal calendar for date conflicts before posting a new event.”
Making it real
Every team’s workflow is different, so I can’t tell you exactly how to integrate the creation of these instructions into your projects. I can give you questions, though, so you can have productive conversations at the right times in your process.
Picking a CMS
If you haven’t selected a CMS yet, consider the following questions when evaluating your options. If the CMS has already been chosen, be aware of the answers so you can adjust your instructions strategy accordingly.
- What formats of field-level help text does the CMS support: single lines of text, paragraphs, pop-ups, hover text?
- Can the instructions include HTML? A bit of simple formatting can go a long way toward readability.
- How hard is it to update the help text? As needs change over time, will adjusting the instructions be a hassle?
- Can you change custom field labels used in the admin interface without affecting the machine name used in queries and front-end display?
Content modeling
Content strategists, developers, designers, and clients or subject-matter experts often work together to build content models. But it’s important to bring regular authors—not just the project leads, but the people who will actually be creating entries on the site—into the conversation as well, as early as possible.
- Review content models and field names with authors before they are finalized. Do the field names you’re using make sense to them? Do they understand the relationships between fields, and what that means for connections between pieces of content?
- Are there places where the new model differs significantly from the authors’ current conception of the content? Larger changes warrant more detailed reminders and help.
- For fields that are subtly different from one another: what kind of information will authors need to distinguish between them and use them correctly?
- If you’ve chosen a CMS with a limited ability to include help text, have you simplified your models accordingly? A model people can’t remember how to follow won’t do much for your content.
Content migration planning
When you have significant legacy content, plan for migration to be its own phase of the project. Talk about what kinds of guidelines would make moving content to the new CMS smoother.
- If blobs in the current site are being split into component chunks, position those field components near each other during migration, since they are all being derived from the same source.
- Create a set of perfect example entries for authors to consult during migration. A set of real content—especially one showing how information from the old site fits into the new model—is a valuable reference tool.
- Consider adding “migration phase” instructions and field groupings, with a separate set of “live site” guidelines to be put in place after migration is complete. The kind of reminders needed while content is being moved are not always the same as the help text for content being newly created.
Design and development
As the design and CMS take shape, designers and developers are in the perfect position to spot potential snags.
- Are any pieces of content making your spidey sense tingle? Is there author-editable imagery that has particular art direction needs? Are there site functions (e.g., “only one piece of content can be promoted to the front page at a time, and promoting a new piece will un-promote the existing content”) that you feel like you’re the only person who understands? Make note of any piece of site content that makes you nervous, and share them with your team so the guidelines address the issue.
- Who’s going to enter the help text into the CMS itself? If the instructions are more tactical, this may be something the development team can do as they’re building out the content models. The content strategist may take the lead for more editorial guidelines—in many CMSes, help text is entered through a GUI rather than in code, so its entry doesn’t necessarily need to be owned by a developer.
- Help text deserves its own QA. It’s incredibly important to see the instructions in context—there’s no other way to realize that a particular piece of text is too long or lost in the clutter, or that the field order doesn’t make sense in the form. The development and client or business teams should both review the edit forms for every content type to make sure all the important information has been captured.
Ongoing adjustments
Revisit your work regularly with both your team and your client or project sponsor. Adjusting the help text or rearranging the fields won’t take much ongoing time, but can make a huge difference to the quality of the author experience—and the resulting content.
- Review live pages, especially any with complex layouts. If you find images that aren’t following art direction or text that isn’t providing needed information, add more specific help text around those issues.
- Chat with the authors using the system and make adjustments based on their feedback. Is there anything annoying about the edit form? Are the fields in an order that works for them? Are there places where a link over to a style guide or intranet page would save them time? Small changes to the interface can make a big difference to the overall workflow for an author.
Setting authors up for success
I used to think it was inevitable: that a few months after launch, I’d be guaranteed to find misused fields and confusing headlines littering a site—the particular kind of chaos that arises from combining a powerful CMS with untrained site administrators. But as I’ve moved the content guidelines into the CMS itself, my post-launch check-ins have shifted away from annoyed sighs and toward small improvements instead.
When we embed instructions where they’re most relevant and helpful, we help our authors build good habits and confidence. We allow them to maintain and expand a complex site without feeling overwhelmed. A website that looks perfect on launch day is a wonderful thing. But when we improve the author experience, we improve the content forever—and that’s a whole lot more satisfying. ..
