By David Gardiner | Student Member
Imagine interactive infographics in Web app documents that show an overview of concepts, tasks, and reference information. Parts of each infographic—lines, shapes, text—are hyperlinked to take users to different parts of documentation. Imagine users displaying videos inside illustrations, turning graphics on and off in a browser, viewing screenshots with annotations overlayed, and even displaying text in a user’s preferred language. This is what scalable vector graphics (SVG) can do for Web-based technical documentation (http://svgdocs.net/svgtechcomm.svg). In this article, I state the case for using the Web technology of interactive SVG to produce visual technical documents to shortcut the process of writing and create an engaging user experience. The article gives an overview of:
- using HTML5 technologies with SVG
- replacing text with hyperlinked infographics
- integrating visuals with text documents for mobile and Web apps
- single-sourcing graphics for translation/localization
- conceptualizing and drawing SVG
Web documentation is now produced for mobile devices, often with mobile-first production, and technical communicators faced with this workflow realize a need to develop “visual literacy” to create effective graphics for Web app documents. We still largely use images to supplement text, such as screenshots or photos, or even technical illustrations that are typically converted to images in their final form. But there are compelling reasons to start using SVG as an enabling technology because it’s now part of HTML5, and all browsers and mobile devices can display the format.
Replacing written concepts and tasks with hyperlinked infographics, or hypergraphics, has considerable potential to improve the user experience because these act as shortcuts to understanding concepts, carrying out tasks, and finding reference information quickly. Hypergraphics can potentially enable documentation—presently structured as conventional, linear, book-like text—to be fragmented into very small topics yet still accessible using graphics as the interface for finding information. It also opens up technical communication to best practices in Web and mobile design, because succinct visuals linked to small topics convey more meaning and grab the attention of users who now expect an interactive experience akin to using smartphones.
Writing documentation can be onerous due to the time it takes to craft comprehensible text, which ultimately gives many users superfluous background information. Users expect fast learning and quick answers, so presenting small and disparate Web topics that are linked through visuals can begin to satisfy those needs. The idea of sketching documentation might also come more easily to new technical communicators used to a world of visual information—the thought of learning how to write all documentation may seem archaic.
To demonstrate how a visual interface to Web documents might look, Figure 1 shows procedures in a hypergraphic, represented by arrows between infographics (main tasks) that are hyperlinked to other explanatory infographics.
Hyperlinked infographics can resemble the product or service being documented, and users can touch parts of graphics for more information about features. Technical communicators can design a visualized document structure around intuitive point-and-click actions instead of structured searching and reading. This experience has previously been available mainly with Flash multimedia presentations (think of touch-screen kiosks), but SVG and browsers now make it possible with far simpler tools—it is an enabling technology for media-rich documents.
The Case for Hypergraphics
Technical communication practice is still wedded to the idea that infographics are static representations of concepts or processes that technical documentation explains and summarizes—diagrams that are merely meant to be viewed to help a user understand complex systems. The best knowledge we have to portray visual information so far includes the concepts of “technical comics” and data visualization.
Graphics typically presented in documents include screenshots and line drawings. This has been constrained partly by our preference for raster images or bitmapped graphics that are easy to create, and because paper documents have limitations in how graphics can be presented. But now we need to create content for mobile devices, and there is increasing use of structured authoring for single-source production of both print and Web documents. Documents are still prepared using well-established principles for comprehensible written communication—with the added extra of hypertext. There is now a timely convergence of Web technologies, as well as demand for mobile documentation, that forces a rethink about how documents need to be presented to users who expect interactivity and highly visual interfaces.
HTML5 supports SVG, which means you can display line illustrations in Web pages. Meanwhile, tablet and smartphone operating systems have developed sufficiently so that all mobile devices and browsers can now display SVG. Michael Opsteegh, in the context of visualizing data, says that infographics can persuade the audience, and that readers tend to rely on information conveyed by infographics rather than any accompanying text. So making the connections between these technologies and user expectations leads to an inevitable need for hypergraphics that enable visual-first and mobile-first documents.
Replacing Text
The trend toward mobile technology is accompanied by research into user experience (UX) and usability assessment, where users of products and services drive the development of user interfaces so products are easier to use. While these techniques are used in developing products for markets, they aren’t typically applied to test the usability of documentation. What if the technical communicator could create Web app or mobile documentation where infographics are hyperlinked, so that a user needs to tap on them to get to information, or to step through visual procedures instead of reading them in a sequence of images or lists? That sort of experience makes infographics more meaningful because a user must interact with the documentation instead of just viewing it. Suddenly, it is more worthwhile drawing sketches because they are now integral to the document interface—so graphics are no longer just for passive viewing.
As Alan Porter has stated, we need to consider how users would experience technical graphics. Visual explanations must present users with clear and meaningful visual information in one place, and which provide consistent structure and navigation. Hypergraphics meet these needs by employing best practices in Web usability. They must be styled simply enough to convey sufficient information, and no more than that. Technical hypergraphics should not overuse Web styling simply to look enticing—otherwise the technical communicator runs the risk of spending additional time producing Web styles that don’t mean anything to the user. There is an overwhelming need for minimalist design because the ultimate aim of hypergraphics is to quickly convey information to the user (such as no more than two clicks away) and to provide a stepping-off point to more detailed explanatory text.
Integrating with Web Documents
One example of how hypergraphics work is a Web app documentation product, cop-e-boox™—a bundle of customized publishing stylesheets to produce ebook formats from XML content (https://sourceforge.net/projects/copebooxstylesheets/). This makes extensive use of SVG hypergraphics that users can tap on to find features in text-based stylesheets. The hypergraphics resemble the end product of setting up styles for book layout—they are formatted as pages of a book and users tap on navigation icons to skip to different parts of a book to find features they want to set up. There are options to start viewing documentation as infographics in a browser and then link to text, or to open text-based help documentation as a Web app then link to descriptive hypergraphics (akin to providing separate novice/expert tracks for navigating documents). Because the hypergraphics are designed to resemble the end result of the product or service being documented, it is quick to find features with minimal navigation as the design is intended to be intuitive and self-explanatory. Long passages of text aren’t required if visual design is user-centric.
When you hover the cursor over a graphic, it changes color because the graphics have cascading style sheet (CSS) styles embedded—user feedback for ‘mouse over’ events works the same as for hypertext. Graphics have alternate text that appears in popup tooltips—the same as for images in Web pages. Tapping on any graphic (lines, shapes, text) can open a new browser window, which has further instructions about that feature. Figure 2 is part of a hypergraphic in WebHelp, which shows selected text highlighted in green and a popup browser window with reference information.
In this documentation, concepts are described in conventional written WebHelp pages (e.g., what XML mark-up to use). Tasks (such as how to interact with the hypergraphics using mouse-based zoom and pan) are outlined in a single infographic that shows the structure of software components. Other hypergraphics essentially act as entry points to reference information (what book styles to set up in stylesheets and how to specify values)—these might be the visual equivalent of summary tables. The reference information is presented in very small snippets as HTML files (first presented as infographics, then with links to explanatory text) that the user can dip into quickly.
While there are infographics that appear with minimal text in each SVG file, the overall design is based on the product that a user would create or use. Another aspect of this design is that much of the reference information is highly fragmented as stand-alone topics. Hypergraphics can link to very small Web files containing only as much information about each feature as a user needs to know. This circumvents any extraneous information about other features, so a user is not confused and slowed down by lots of superfluous detail about other features or functions (as might be found in conventional summary tables).
Applications
Because conceptualizing and drawing visual documents is a cost in the time it takes, there needs to be a benefit so that hypergraphics are a feasible part of the documentation workflow. Apart from creating a more engaging user experience that shows only relevant task-based information, hypergraphics can fill gaps in delivering content.
An obvious application is for translation and localization. SVG mark-up has the clever feature of being able to display multilingual text in a browser. During document production, a translator can type translations into an SVG file using a text editor and special coding in the mark-up specifies the language of each piece of text. As the end result, when a user viewing the graphics sets their preferred language in browser preferences, the browser interprets this coding and switches languages. In a way, this is “single-sourcing” graphics—a technical communicator draws infographics once, and adds multilingual text to “reuse” the visual content depending on how a user chooses to view it. It means there is no need to create multiple images for each language when producing graphics.
It’s also possible to put Web content inside an SVG graphic. For example, HTML-based summary tables can be added next to visuals where explanatory text is needed. This capability also means that a user can view embedded videos next to graphics, which has benefits for presenting e-learning material. A more simple application could be to put icons on the first page of complex online documents and create “quick links” to frequently accessed pages. This mitigates the need for users to first become familiar with the structure of text documents before they are able to find what they really need.
Styling infographics
SVG has a lot of capability for styling graphics, because CSS styles as well as SVG styles (filters) can be applied to hypergraphics in a similar way that they are used to style objects in Web pages. It would be easy to get carried away styling text, lines, and shapes in attempting to present a sophisticated, glossy user experience that one might have when using software or apps.
Don Moyer warns against using special visual effects in depicting sketches, as they overshadow the structure of the story that visual explanations are meant to convey. This is certainly the case when confronted with the plethora of styles and animations that CSS offers. The technical communicator needs to limit styling to what actually conveys meaning and understanding. A user will still only look briefly at an infographic, then tap on it to find information.
Software and Skills Needed
Technical communicators can use standard illustration software such as Adobe Illustrator to draw graphics then export them as SVG. There are also specialized open-source SVG editors such as Inkscape, which lets you add hyperlinking to any graphic element. With sophisticated text editors, one can set up and add CSS styles to graphics and even embed JavaScript coding so that when a user taps on a graphic, a browser window opens with more information.
Hypergraphics combines the principles of Web design and information design. Conventional infographic design plays a large role and has well-established techniques for visualization. But extending the concept to where the design process restructures written documentation into fragmented and modularized visual-first interfaces means also including aspects of data visualization (which is increasingly using interactive SVG), designing for user assistance and usability assessment.
The challenge lies in conceptualizing visuals and making the design relevant as entry points into documentation. Technical illustrators can play some part, especially where they routinely design more complex illustrations as part of conceptualizing products. Yet, as multi-skilled technical communicators, we need to build on our strengths in managing production by integrating those designs into documentation—structuring, hyperlinking, and styling to ensure accessibility and usability for good user experience. By producing Web documents, we already have gained many of the skills in mark-up languages to start creating hypergraphics. We now need to apply our skills in new areas to create value-added documentation.
Dave Gardiner is the owner of Xmplar, a document authoring and publishing support consultancy. He has over nine years’ experience in technical and scientific document editing, redrawing, and ebook authoring. He is currently studying for the tekom first-level certificate in technical communication. He specializes in developing XML publishing workflows and has developed open-source stylesheets. He has also delivered industry workshops and presented at national conferences. He has published articles on digital publishing technologies and can be found at http://xmplar.biz.
References
Cop-e-boox stylesheets, https://sourceforge.net/projects/copebooxstylesheets/.
Scalable vector graphics for technical communication, http://svgdocs.net.
