Training is the most exciting part of a project. It’s the point when our team hands over our hard work and shows our clients how the final product will actually work for them. It can be really hard to get everyone in a training session at one time. Even then, knowledge imparted from classroom-style trainings can easily be forgotten if not written down. After our trainings, we deliver a written handbook for editors to reference as they work with their new site. Here are a few of words of wisdom that make a handbook useful and usable for your content managers!
Living Documents Should Live Online, Not on Your Desk
A lot of organizations print their handbooks. They want something that flips open as a reference. The problem is that information quickly becomes out of date, especially as your website iterates over time. This results in different staff members having different versions with different information, causing confusion that is easily avoidable. By keeping your handbook digital and accessible via a single URL, everyone always has the most up-to-date copy.
If you must have printed copies, make sure they display a version number, like “v. 2.1”, and date on the cover. In the version number, the first number should be used for large changes, like new fields or content types, and the numbers after the decimal for small updates, such as corrected typos or further clarification.
Online documents also allow the user to quickly skip to specific sections. This is much easier than trying to flip to the right page, and makes it simple to share knowledge by sending teammates a direct link to the most pertinent help text. Once you’ve gone digital, the Internet is your oyster.
GIFs and Screenshots Lead the Way
Skitch has long been our favorite for annotating screenshots. The hard-to-miss, hot pink annotations are designed to clearly stand out against brand colors. Everyone on the team, clients especially, love Skitch because clarifies each element of a screenshot.
Screenshots are helpful, but animated GIFs can be even better at precisely illustrating exact steps. With Google Docs, you can use animated GIFs right inside the document! LICEcap is a great tool for recording straight to GIF, because it saves time by avoiding conversion from video. GIF Brewery is another great option.
When recording GIFs or taking screenshots, try to focus in on only what is relevant. Don’t capture the whole computer screen if all that matters is a link in the upper left corner. Provide just enough context to orient the learner and nothing more.
Use Landscape Layout
Computer screens are usually landscape layout. So, a document that’s also in landscape layout provides more room for screenshots that show more detail. In Portrait mode, pictures can get squished and unclear.
Use a Different Font for Nomenclature
Just like in any Computer Science textbook, it’s important to distinguish conversational language from specific application terminology. For example, to someone who isn’t familiar with Drupal lingo, the following sentence could be confusing:
To find your content, click Content in the upper left hand corner. Then click the Content type drop down and press filter.
The word “content” is used several times in the sentence and could easily be misinterpreted, even with capitalization. Font treatments like bold and italic could be used to indicate emphasis or phrasing in the handbook itself. So, using a different font creates an obvious distinction. In Computer Science fashion, a monospaced font looks different enough that there should be no ambiguity.
To find your content, click
Contentin the upper left hand corner. Then click theContent typedrop down and press filter.
See, it’s just a little easier on the eyes!
Remember your Audience: Avoid Technical Speak
As experts, it can be all too easy to rely on industry jargon to communicate. Unfortunately, this contradicts the whole point of the handbook! Many times, jargon words can be deleted altogether, or swapped out for a more accessible synonym. Words to watch out for include:
- View
- Display
- Field
- Node
- Output
- Reference
- Configure
- Override
- Interface
- ...the list goes on
Basically, avoid any words that have either no real-world use outside of the application (e.g. Node) or have a different real world use outside of the application (e.g. View, Field). Explain concepts via their content, rather than by the software architecture terminology.
Include Context and Other Helpful Instructions
Content editors aren’t always aware of the strategic decision-making that went into the new software. Explain to the reader what the larger strategic goals are when instructing him or her on how to use a bit of functionality. For example:
A Community Story is intended to share accounts of the work we do with the organizations and non-profits beyond our revenue-generating work. These stories will show that we’re invested in our community and enjoy giving back.
It can be helpful to reiterate help text from the application in the handbook, though be mindful of the help text becoming dated. Image dimensions and copy length are often more obvious in the handbook than in the subtly styled help text on the site. The handbook also allows you to include visual aids to show where information will appear, which isn’t usually an option with in-software help text.
Avoid Redundancy and Only Highlight Uniqueness
Repetitive steps and phrases will make eyes glaze over. Instead, explain key concepts and then specify only the differences when working through similar items. For example, explain in general how to add content. Then, for a particular content type, hone in on what is unique to that type. This saves time for the learner and teaches skills through repeatable steps.
Every project and client is different so, inevitably, not all handbooks look alike. Each time we make a handbook for a project, we learn something new, not only about what we do as a company, but also about human nature. Training can be a challenging time for the agency and the client, but a great handbook can go a long way in putting everyone at ease.
