Questions to answer before you start

What is this service best used for?

• Identify its strengths and plan to focus on them.
• Come up with a one-sentence-maximum description of it that will help a complete novice understand what he or she is looking at.

Who is providing the information about the topic you’re going to document?

• If it’s the manufacturer, do they have any good documentation you can model from or get permission to redistribute?
• Are any other universities using this service?
• Have they got good documentation?
• If you write to them and ask nicely, will they let you reuse their stuff?
  (Quite a few CITES documentation suites are being reused at other websites; a lot of our Lync documentation came from Pennsylvania and Kentucky; and for many, many years, CITES’ Cisco VPN documentation was the #1 hit on Google for that search, significantly beating out Cisco’s own docs.)

What groups of people (audiences) are going to be reading your documentation?

• The answer to this is frequently more than one audience with differing needs. List all of them here. This sample covers “service users” and “service administrators”, but you may also need to create materials for student help desk employees, marketing and communications staff, and more.
• Keep in mind that you can share some documentation between different audiences, but not all of it. Service administrators will need different documentation than service users.

In addition to you, how many people will be contributing to this documentation (if any)?

• Crowdsourcing distributes the work load. It also needs an additional layer of documentation to be created (to communicate to the crowdsourcers what you want and where to put it).
• Create contingency plans when you plan to use crowdsourcing. What happens when no one else has time to work on it either? Do you make personal assignments to individual people, or to working groups?

---

Build your framework

Assuming the following example answers to the above questions:

• Morning Widget is an email and calendaring plugin that will check your class schedule, brew your coffee, toast your bread and scramble your eggs in the morning, and send a text to your mobile phone to wake you up when your breakfast is ready.

• The manufacturer seems to have run its documentation through Babelfish; you can’t count on reusing anything they wrote.

• You need documentation for:
  1. The residence hall system and network administrators who will need to install personalized instances of Morning Widget that connects to their residence hall’s cafeteria equipment
  2. The sleepy students who want a one-click solution to getting Morning Widget installed and running, since they haven’t had their coffee yet

• You’re the only person writing this documentation

Use page titles and headlines as outline points

Using page titles and headlines as outline points allows you to condense two steps into one. It’s also a lot easier to see the flow of your pages and shuffle things around at the “bones” level before you’ve put a lot of time into writing content.

Sample page structure and headlines

Users’ starting page:
morningwidget/index.html

• Page summary: (Your one sentence blurb)
• Who can use Morning Widget?
  • Residence hall students living in FAR, PAR, ISR, and Allen Hall
  • Anyone who owns a Breakfastomatic 9000

• Getting started with Morning Widget – morningwidget/install.html (download, installation, and configuration) – see software installation templates for more details here
  • iPhone – morningwidget/iphone.html
  • Android – morningwidget/android.html
  • Blackberry – morningwidget/blackberry.html

• Using Morning Widget – morningwidget/use.html

• Help & Troubleshooting – morningwidget/help.html

• For Morning Widget Administrators – /morningwidget/admin/index.html

Administrators’ starting page:
morningwidget/admin/index.html

• Applying for a Morning Widget installation in your location

• Morning Widget system requirements
  • Breakfastomatic 9000
  • Network infrastructure
  • Firewall ports 1234 and 5678

• Supporting your users
  • Handouts, flyers, text message templates

• Support from Morning Widget HQ
  • Upgrades and patch releases
  • Service level agreement
  • Contact Morning Widget HQ

Particular points to note in this structure

Keep the gory technical details separate from the getting-started documentation. Emphasize the ease of use to the users. Emphasize the power, flexibility, and complexity to the admins.

If you have undefined acronyms on the end user pages or don’t have undefined acronyms on the admin pages, you’re probably not keeping your audience focuses distinct enough. Undefined acronyms include what IT pros think of as “common knowledge.”

Keep the installation and configuration docs separate from the use docs. Typically, people only have to install something once. They use it a lot more than once. Don’t make them scan through all the installation instructions whenever they want a refresher on how to use it.

Break out the documentation by platform as appropriate. I’m assuming here that MorningWidget’s user interface looks pretty much the same across all platforms, but that the download and installation process is smartphone-OS individualized. If a service’s installation was identical but the way to use it varied between platforms, then making one installation page and multiple use pages would be better.

Once you name a page (or a PDF or Word document), don’t rename it short of nuking the site from orbit. You never know who’s linking to it from Google, from other sites, etc. If you have a printable MorningWidgetQuickStart.pdf, and a replacement copy comes out named MorningWidgetQuickStart-20110712.pdf, just standardize the name again rather than break everyone’s bookmarks and links. Keeping track of when each version was released is the CMS’s job, not the end users who just want to find it again.

Standard heading levels: The perfect intersection of accessibility and laziness

After you’ve created your page and heading structure, turn them into pages and headline levels (or both). For example, in the outline above, “Getting started with Morning Widget” is both a headline item in index.html and the title of the page that will become install.html, which will contain a link to Webstore (or wherever you download it from) and the various platform-specific breakout pages.

Instead of visually formatting everything to look like headlines by applying size changes and bolds or underlines, use the standard heading levels that are already built in and style them with CSS.

• Standardized heading tags (H1, H2, H3) can often be used for self-updating tables of contents – the wiki uses the {toc} tag for this, and many CMSes have a similar feature.

• Accessibility rules say that H1 is the page title, H2 is the first level beneath it, and so forth. There’s only one H1 on a page. There can be any number of H2s, H3s, H4s, etc.

• Style the headings once with your CSS and it’ll look consistent everywhere. Change your mind? Change your CSS and you’re done.

Accessible lists > everything

• In addition to improving skimmability, they also improve accessibility when you name your lists
• List-driven menus are more accessible than visual-driven menus
• One-dimensional “tables” should be converted to lists and CSS styled

Filling in your outline

Core principles:

• Put your page summary – a one sentence statement of what the page is about and who it’s for – at the top of the page, right under the headline.

• Skimmable is good.

• Screen shots are good for novice end users but can also be frustrating for experienced support staff who’ve done it a dozen times and want to see or print the quick outline version.
  • CITES makes pages customizable by making it possible to show or hide images by choice – all on, all off, or one at a time. That way each page visitor can see what he or she wants to see.

• If a paragraph takes up more than 4 lines of screen, you probably need to split it up and/or cut it down.

Speed tips

Take screen shots of every single screen, in order, on your first run on each platform.

You can’t completely duplicate the experience of never having seen it before, and that’s valuable to catch because that’s the boat your users will be in.

In addition, some things don’t completely un-install, so once you’ve done it once on a given computer, you’ll never get the same set of prompts again.

• Capture every screen
• Number them in sequential order so you can precisely reconstruct the sequence later
• Windows 7 offers a video-screen capture facility built in (psr.exe)
• I don’t know of a built in option on any other OS, but Jing is free and works for earlier versions of Windows. You can’t take screen shots out of it easily, but you can use it to memory check yourself later.

If you don’t have to reboot during the process you’re documenting:

• Make yourself an online meeting in Lync
• Join your own meeting
• Turn on the sound recording and either full-screen share or application share
• Talk to yourself while you’re doing it
• Mention out loud when you get confused, because other people will get confused there too

Write through the perspective of a persona who’s the primary audience of the page.

More about personas below, but if you can put yourself behind the audience’s eyes and take notes from that person’s point of view, you’ll be running a partial usability check during the initial composition process.

• For end user documentation, you can run the Grandma check. Make sure everything you write would make sense to your grandma (assuming that your grandma does know how to follow links to explanations and other pages).

• For IT pro documentation, use the perspective of an IT pro who is a member of the group that will be receiving your service, not one with your background knowledge in developing the service.

• If you’re documenting how to get a Morning Widget system running in Allen Hall, use the perspective of an Allen Hall system and network administrator who knows his own network and systems but doesn’t know the Morning Widget system. Don’t use the perspective of a Morning Widget engineer.

Preflight check: Include your audiences

Best option: Run a miniature usability test on your documents.

• Locate a member of each of your audiences.

• If possible, find both someone who’s never used this service before and someone who is already familiar with it.

• Have them read through the documents, preferably in front of a computer that doesn’t already have the service where they can try to follow along from the start.

• It’s OK to tell them that you’d like for them to read through your documents and see how well they work. Don’t tell them anything about the service itself. They need to get everything they need to know from your documents. They won’t be able to do that if you’ve told them things that aren’t on the page.

• Don’t point or um or squirm. In fact, if you can get out of the room and have someone else watch them use the documents, do it. You don’t want to be able to feed them nonverbal cues about the documentation either.

• Do tell them that if they have problems, it’s not THEIR fault. If people have problems using a service, either the service itself needs adjusted or the documentation does; often, it’s both. This review is for you to see where they have problems, what problems they have, and hopefully come up with ideas to reduce their problems.

But, you don’t always have time to run through this whole process before publishing things. So then there’s the second-best option.

Second-best option: Use personas, aka the “grandma check.”

In a nutshell, personas are a mental role-playing exercise that you use to look at your work through someone else’s perspective. Personas need to be detailed enough to stick in your mind the way real people do.

Simplest user persona check: Grandma

• If you put your documentation in front of your grandmother, what would she want to see?

• Where would she get confused?

• What terms would she or wouldn’t she know?

The more you can Grandma-proof your end user documentation, the easier your support staff will have it.

More complex persona checks

The biggest reason to have a stable of personas is because Grandma is probably not fully representative of your end user audience in a college environment. And she’s definitely not representative of your IT pro audience.

Note: You’re not even representative of your own IT pro audience, because you’ve had to learn the system in the process of getting it up and working. You know things now that you didn’t when you first got the product. Keep that in mind when you’re writing for fellow IT pros.

Some of the personas I use most frequently for mental reference checks:

• An education graduate student for whom English is not the first language
• A history professor in his 50s
• A dean of social work in her 30s
• An administrative assistant (I use my mother in specific)
• A highly socially networked student who’s more accustomed to Facebook and Google and Microsoft and worldwide services than campus-limited ones
• A graduate assistant from another university interested in collaborative research