Publishing

A lot of companies are evolving the manual with online publishing platforms. There are wikis, like this fanmade user’s guide for SecondLife. Instead of the standard PDF, Sony created a custom, online instruction manual for the PlayStation 3. Many companies are deploying tablets onto the factory floor, replacing PDF work instructions with mobile documentation stations.

These days, everyone has a smartphone in his pocket and a tablet on her bedside table. Information is mobile—your manual should be, too. Optimize your manual for mobile devices. PDF manuals don’t work well on phones. They’re too dense, rooted in paper’s legacy fixed-width format, and difficult to search and navigate. They work better on tablets, but miss out on much of the advanced functionality that's now possible.

Information in your manual should also be easy to find, no matter how you choose to publish. Users hate flipping or scrolling through hundreds of pages to find the one sentence they want. So, if you’re publishing on the web, integrate a kickbutt search feature. If you’ve written a hefty print manual, write a table of contents and an index.

Making your manual easy to browse on the web has another key advantage: it’s available through Google. Most users google information before they go to the manufacturer’s website. Google is the primary user interface for iFixit—most people find our instructions via web searches.

Make your manual easy to find on the web. Think about what potential users might type into their Google search boxes when they’re troubleshooting, and use that language in your manual. Plan to adapt your manual in the future as people shift their search terms.

Accessibility also means optimizing for different types of audiences. Done right, web manuals are very accessible to blind readers, and anyone can use a translation service to see a web manual in their home language. It’s impossible to get the same sort of accessibility with a paper manual, and it’s hard to do with a PDF.

Getting better: Knowledge management

Publishing isn’t the end of your job. Documentation needs to evolve. Make no bones about it: your manual will go out of date at some point—and often in ways you’d never expect.

• Sometimes, the writing itself is the problem. Hey, we’re human and writing is hard. Every once in awhile, writers make mistakes. And when that happens, people start breaking things. That’s okay. Version 1.0 of any product—software, hardware, or manual—is never perfect.
• You may find an easier way to approach a task. Maybe it's easier to use a flathead screwdriver than a Phillips; maybe there's this new tool that makes something incredibly easy; or maybe an assembly line worker found a faster way of assembling the product, etc.
• Other times, the product itself changes. The production line can change after the manual was written: they add screws, reconfigure the mold, or make other minor (or not-so-minor) changes.

Plan for the inevitable. If it’s hard to publish changes, you’ll likely be less than eager to update your documentation as frequently as you should.

If it’s at all possible, we suggest a publication method you can easily update. Unfortunately, there is simply no easy way to update a paper manual. In an Air Brake and Train Signal Manual from 1910 (pictured below), the authors literally pasted updates directly over the outdated information. In 2012, Toyota had to recall thousands of cars because they botched a couple sentences in the manual.

Publishing a PDF doesn’t offer much more flexibility. If you’ve released 1,000 PDF manuals onto 1,000 laptops, you’ll have to update all of them manually. No fun. And what happens if a safety-critical update misses 5% of your field technicians? That’s just one reason we tend to advocate central data storage instead of the standard print/PDF workflow.

Integrating feedback

You need your customers—not just to keep your business alive but also to keep your content thriving. Your customers make you better. The more feedback you have, the more suggestions you get, and the better your documentation (and your company) will be.

Customers can point out where text is confusing; they can tell you when an image just isn’t helpful. Recruit users to help you improve your manual. If you publish online, give users a directed Q&A venue for feedback and editing suggestions. If you publish in print, give readers someone they can contact for questions and feedback.

API means write once, publish everywhere

Google Maps is installed on millions of smart phones in America. Even though Google is constantly updating and expanding their maps, users always get the latest version of the map. How is that possible? Because the information people want isn’t downloaded into their phones—and they don’t have to re-download the application every time Google updates the map. The information lives elsewhere and constantly publishes updates to all connected devices. It’s an API.

API stands for Application Programming Interface: if you publish online, it will help you seamlessly update your documents. Traditionally, document updates are pushed through Word, maybe to inDesign, then PDF, then onto the web, to techs, and to the archives. And if you make a change to the text in Word, that change needs to make its way to every other format. By the time everyone has an updated copy, it’s time to update again. Using an API allows you to make changes to one central hub. Those changes are then pushed out immediately to every single other publishing platform.

Modern documentation formats like oManual include API specifications, and documentation systems that support mobile apps are starting to take advantage of this.