“Manuals are rapidly becoming the last items people rely on to find information about the products they have purchased. Leafing through the pages of a printed copy seems too old today. In fact, even finding the printed manual may be difficult in most environments. Instead, we search for answers to our questions using the ubiquitous Google search. Most of the manuals that were in our kitchen drawers are available online but do we really want a PDF of a manual to try to page through? Instead of a PDF, we’d like a page with the answer, something we often can’t find without going to the product website. Topics are the new information resource.”
– JoAnn Hackos, Comtech Services
In Defense of the Manual
We can carry printed manuals (well some of them anyway), make notes in the margins, and perform random searches. There’s no need for an intermediary technology – all we need is the ability to read. That said, paper manuals have a number of disadvantages:
- They are easy to lose
- Paper deteriorates over time
- The manual may or may not have an index
- No hypertext
- No video or interactive graphics
- The content is difficult to update
Not long after the introduction of desktop publishing in the mid-1980’s, technical writers got the sense that there were new possibilities embedded in the seemingly endless chunks of content that could be created on these systems. But at this point, we were just using the tools to prepare manuals for printing to paper.
Enter the PDF
The introduction of PDFs around 1991 provided a way to move past print runs and to provide electronic copies of updated content much more quickly – and cheaply – than a traditional hard copy.
PDFs offer many advantages over traditional publishing. They are available on all operating systems, offer a consistent look across devices, can be downloaded to use offline, enriched with multimedia, and are portable and printable. But PDFs are, at times, hard to navigate and difficult to search. At the end of the day, we were simply creating electronic versions of manuals.
The Rise of the Internet
As the internet took hold, we began to use HTML and hypertext to deliver content to the web and yet, while we used all of these new tools, our mindset remained within the paradigm of the document – and ultimately of, the manual. We experimented with Information Mapping and SGML as ways of structuring content and tagging content. But the dominant metaphor was that of the manual.
HTML is essentially how we publish to the web today and has a number of advantages over PDF:
- Comments, annotations
- Live code and data
- Detailed user data
- Sortable references
- Add video, animation, and audio
However, there were a number of drawbacks as well. HTML pages don’t look like documents, are harder to archive and share, can look different across devices and even browsers, oftentimes can look cluttered, and cannot be used offline – at least not easily.
The introduction of DITA gave us a way forward.
DITA provided us with a way to create content based on creating topics and not books. As writers and developers of content, we understand that users don’t read a manual because they want to savor the lean, technically pristine content we write. They use our manuals because they want to perform a task or solve a problem. And traditionally, they had to wade through pages and pages of content just to find the answer they needed.
Customers want more. JoAnn Hackos mentioned that 87% of companies she surveyed are publishing to PDF and 66% are publishing to the web using HTML. Only 33% are using what she termed dynamic publishing. And it is the move to dynamic publishing that will finally allow us to move beyond the paradigm of the technical manual once and for all.
A dynamic publishing environment (also referred to as a knowledge base or content portal) is a web application that pulls content from a production environment and delivers that content to users in a way that is:
- Easy to use across different devices
- Allows for personalized content
- Allows for end-user feedback and review
- Provides user and content analytics
- Ease of sharing at the topic level rather than at the document level
Internally, Innovatia is already working to deliver content via a knowledge portal and has a portal up and running. The intent is to provide content searchable at the topic level, customize content for specific customers, shape content for each role in an organization, and provide PDF outputs and access to multimedia content, where applicable.
It’s About Customization
Rather than having to work through an entire documentation suite for information on a specific feature, users will be able to search the knowledge base and receive a “customized” manual that will include all available information on a specific feature – from installation, to operation, to maintenance and troubleshooting.
What this means for writers is that the focus of our writing must be at the topic level. We need to think less and less about delivering a “manual” and instead focus on creating topics that are both standalone, and at the same time can be integrated into a workflow when combined with other topics related to that feature or topic.
This portal and others like it will, rapidly replace both plain PDF and static HTML as the go-to source for content for users.
The Door Marked “Enter”: Transitioning from Manuals to Web Content
From Manuals to Articles
So you’re moving from delivering book-based content to web-friendly...
The What, Why, and How of Great Engineering Specifications
Pretty much every company that creates or purchases products or materials needs technical...
What makes an effective portal
Technical documentation belongs on the web. Unless your product is top secret or your customers...