HTML5's Impact on Technical Documentation

HTML5 and the Future of Technical
Documentation
By: Jessica Morley
May 2015

HTML5 and the Future of Technical Documentation
2
Introduction: A Crossroad in History
Introduction: A Crossroad in History
echnical writing is at a crossroad in history. Gone are
the days when people read technical documentation
from print in manuals, books, inserts, or pamphlets.
Likewise, the practice of reading documentation from a
CD Rom or desktop software application is quickly becoming a thing
of the past. Today, if people want technical information, they go
straight to their browsers to find what they are looking for.
With the advent of handheld smart phones, laptops, and tablets,
teamed with the ubiquity of reliable internet connection
everywhere, people demand versatile, responsive, and accessible
documentation that can meet their information needs. HTML5, the
new HTML standard officially recommended in October 2014, is the
World Wide Web Consortium’s (W3C’s) answer to this new age of
high-speed on-demand information, and technical writers are
beginning to take notice. However, the question remains: should
technical writers adapt to this new wave of technology, and if so, to
what extent will HTML5 impact the user experience and the
technical writing process?
There are a growing number of technical
writers just shy of entirely enthusiastic for this
brave new world of technology. Peter Lubbers,
an experienced technical writer, published
author, and current Senior Program Manager
at Google, is one such individual who may tip
the scale on the enthusiasm spectrum. In his
webcast, HTML5 and its impact on technical
communication, Lubber explains that just as
DITA has made “quite a splash” in the world of
technical communication, HTML5 promises the
same kind of profound impact.
This is not to say that HTML5 and DITA will
become competitors; on the contrary, Lubber
predicts that technical writers will continue to
author in DITA, but HTML5 will replace XHTML
output that many writers have grown attached
to. While the transition to HTML5 may present a
learning curve for technical writers already set
in their ways, the benefits just might outweigh
the burden.
T “Where the
previous generation
looked to books for
their answers, this
and future
generations are
looking to the
internet.”
–Joshua Honomichl,
Senior Tech Writer at
Thermo Fischer
Scientific
FIGURE 1: Since 2014 the world has passed the mobile
tipping point as more people use mobile devices than
desktop computers.
Source: Morgan Stanly Research

3
Why HTML5 Matters to Technical
Why HTML5 Matters to Technical Writers
Joshua Honomichl, a Senior Technical Writer at the biotechnology
product development company, Thermo Fisher Scientific,
understands that the needs of his customers are changing rapidly.
As a long-standing web deployment advocate, Honomichl is one of
the key people on a committee responsible for the next stage in
document evolution.
As it stands, Honomichl is in the early phases of deploying SuiteHelp,
a popular web help framework that works with his content
management system to deliver online help using HTML5 output. Like
many technical writers, he is excited about the potential HTML5 will
bring to his company, believing it has the power to optimize user
functionality and “leverage content in ways you could not possibly
imagine.”
Accessibility and Responsive Design
One of the biggest ways HTML5 leverages content is by utilizing
adaptable, responsive design for customers who need on-the-fly
technical documentation. Vikram Verna, Product Manager at Microsoft and former Product Manager
at RoboHelp, points out that while customers have been able to access help on their mobile devices for
some time, without HTML5 support, the end-user
experience is often “extremely poor.” Conversely, by
outputting with HTML5, technical writers can offer
navigation, sizing, amount of content, and other
features that automatically adapt on any device or
operating system, making documentation useable,
no matter what the circumstance (Samuels).
As statistics prove that people now use mobile
devices even more than desktop computers, HTML5
technology may be the key to improving the modern
user experience. Peter Lubbers, in his comprehensive
book, Pro HTML5 Programming, argues that HTML5’s
innately responsive design demonstrates the new
standard’s commitment to universal access by means
of accessibility, media independence, and
localization support for all world languages.
One key example of localization support is HTML5’s
new “translate” attribute. “Translate” lets content
writers manage specific words directly in the code,
enabling a more flexible and accurate localization
FIGURE 2: The right image shows a table of contents that
HTML5 has optimized for a desktop screen, while the left
image shows a smart phone display optimized for touch.
Source: http://iconlogic.blogs.com/weblog/help-systems/
“Imagine the level
of customer
satisfaction that you
can achieve by
offering the content
on the device which
is carried all the
time.”
– Vikram Verna
Product Manager at
Microsoft

4
outcome for multi-language compatibility. To demonstrate this point, picture a user manual for a new
line of Thermo Fisher water purifiers, which tells the user to click the “RESET” button on the control panel.
When translating the user manual, terms referring to the machine’s physical labels should stay in English.
By using “translate = no,” HTML5 output will instruct automated translation engines and workbench
translation tools to lock the indicated text of that element in place, effectively disabling translation for
the selected word. Translate is just one feature out of many that demonstrate HTML5’s great potential in
dynamic, accessible technical communication.
.
Semantic Elements
Technical writers who appreciate XHTML and DITA for
their semantic nature will welcome HTML5’s inherently
semantic coding environment. HTML5 adds a number
of new semantic tags that give a better definition to
the various elements that form the structure of a
webpage. In turn, these semantic elements clearly
define content, making data more searchable through
search engines, and consequently more accessible to
users.
Not only do these semantic elements replace abstract
and obscure tags, they also work to simplify the writing
process by reducing supurflous code. One key
example (out of many) is HTML5’s new doctype
declaration. The doctype declaration is the first piece
of code in every HTML document, and it instructs the
web brower on what kind of version of HTML the document is
written in. The markup example in Figure 5 demonstrates the
difference between the combersome doctype declartion of
XHTML and HTML5’s simple and easy-to-remember doctype
declaration.
Before Translation:
<p>Click the <span class="panelmsg"
translate="no">RESET</span> button</p>
After Translation:
<p> klicken Sie auf die <span class="panelmsg"
translate="no">RESET</span> schaltfläche </p>
FIGURE 3: HTML5’s translation feature supports versitle
technical documentation.
FIGURE 4: Example webpage layout with
semantic HTML5 elements. Each tag gives
clear and simple meaning to the code.

5
Lastly, semantic elements can help build dynamic technical
documentation. Honomichl is particularly excited about the
leveraging potential in the new semantic tag <article>, which
works to define self contained, independent content within a
webpage. He argues that by embedding subtopics within topics
using <article>, he can easily integrate promotional writing with
technical documentation.
Interactivity
HTML5 promises to give technical documentation a new life with
engaging, interactive features. With HTML5, technical
documentation can easily incorporate dynamic images, audio,
video, graphing calculators, geolocation, or drawing tools, which
the end user can interact with directly in the browser. Technical
writers are particularly interested in using scalable vector graphics
(SVGs) combined with HTML5 to create compelling infographics
for the increasingly visually literate end-user.
Unlike rastar image formats, such as screen shots or purpose drawn
technical illustrations, SVG is a high resolution format for illustrations
that can create texts, shapes, embedded images, animation, and
hyperlinked infographics (hypergraphics). Users can engage with
<article>
<h1> What is Thermo Fisher Scientific’s Mission?
</h1>
<p> Our mission is to enable customers to make the
world healthier, cleaner, and safer. </p>
</article>
XHTML:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
HTML5:
<!DOCTYPE html>
FIGURE 5: The simplifying powers of HTML5 makes life easier.
FIGURE 6: <article> allows technical writers to create dynamic documentation.
“The HTML5
Mantra? ‘Simple is
better. Simplify
whenever possible.’”
– Peter Lubbers
“With HTML5,
users log on to the
website, enjoy the
interactions, scroll
down and then enjoy
it even more.’”
– Vivek Ramen,
contributing author at
TheServerSide.com

6
hypergraphics at their most simplified level by clicking on icons that work as visual points of entry into
web documenatation. At the other end of the spectrum, and with a little help from CSS and Javascript,
hypergraphics can resemble a product, service, or software, wherein users can intuitively touch
individual components of an object to get more information about specific features.
HTML5 embedded SVG support is not only inherently
interactive, it is also incredibly versatile, creating
multifunctional potential in technical documentation.
Honomichl described a use case scenario in which he wanted
to create a multipurpose illustration for a chemical solvent
product. In this scenario, he also wanted to use this illusration
for different technical documents, but some aspects of the
illustration were not necessary in particular contexts. By
embedding SVGs directly into the HTML5, he could easily
remove particular graphical components to the illustrastion
that do not apply to his content and keep any reqiured
regulatory warning images in place without having to recreate
an entire image.
“Being accessible,
compatible with current
web standards, and able
to be produced with
lightweight desktop
software, SVG is an
attractive proposition for
small documentation
teams needing to develop
value-added products for
mobile platforms.”
– David Garner, SVG Summit
2014
FIGURE 7: Unlike raster images, SVGs easily transform to any size
without losing visual integrity.
OTHER HTML5 INTERACTIVE FEATURES:
<canvas> uses scripting to manipulate pixels
<audio> audio without plugins
<video> video without plugins (no more Flash!)
HTML Geolocation browser embedded
geographical positioning
FIGURE 8: HTML5 interactive features offer end-
users a variety of ways to engage with and learn
from technical documentation.

7
Limitations and Learning Curves
HTML5 asserts a lofty promise for a better, brighter technical
documentation experience, but is it simply bells and whistles amidst the
deafening noise of an inundated web of technologies? As it stands, the
tech industry is still debating on whether HTML5 has the power to please a
diverse array of businesses with ever-changing and highly specialized
needs. Between sexy device optimizing alternatives and the inevitable
cost and time constraints that come with learning new technologies, the
path to sustainable change via HTML5 may be long, arduous, and
potentially impractical.
HTML5 Lacks in Specialization
In the article Trends in technical communication, 2014 edition, by Sarah
O’Keefe, it may appear that native applications are “winning over HTML5”
because they are built and optimized for specific platforms or devices. Not only do native applications
take advantage of the latest operating system technologies, they also offer more offline accessibility, a
cleaner user interface system, and faster processing speeds.
In addition, O’Keefe points out that end-users attuned to the bring your own device (BYOD) trend go to
native applications first for technical support or field services, and consequently businesses are choosing
to build native applications for their content (O’Keefe). For instance, if the technical documentation of
a company is primarily for its employees, the chances are high that these employees will be using a
company-issued device, such as a tablet. As a result, it makes sense for the company to build a native
application on a single operating system (O’Keefe).
“HTML5 is a step
in the right
direction, but
doesn’t go as far as
you need.”
– Joshua Honomichl
HTML5
VS.
NATIVE
Native Apps
 Tailored for specific
mobile devices
means more
specialization
 Faster processing
speeds
 Better offline
accessibility
HTML5 Web Apps
 Runs on any mobile
device via browser
 Cheaper (only
write once for all
devices)
 Search engine
friendly
FIGURE 9: The benefits of native
applications may outway the benefits of
HTML5 web applications, depending on
business and end-user needs.

8
Aside from the native versus HTML5 web application debate, many businesses may be choosing to work
with web content management systems (CMSs) and all the easy-to-use plugins involved because the
architecture of documentation written in a CMS often entails tags that are exclusive to that specific
system. Honomichl is keenly aware of the shortcomings HTML5 presents, explaining that in a web
environment it’s important to create specialized tags and data chunks that are exclusive to the
company, allowing them to format against public databases. Moreover, while HTML5 offers general
solutions by casting a wide net over the World Wide Web, it simply “can’t make everyone happy”
because people will want to hang onto their core group of elements (Honomichl).
HTML5 is Harder
While new semantic elements make it easier than ever for technical
writers to learn HTML, learning a new markup language may be a
time intensive investment. Many avoid HTML5 simply because it’s a lot
easier to implement CMS plugins than to invest the time into learning
HTML5 code to create cross platform harmony and develop HTML5
interactive features. Not to mention, to take full advantage of
HTML5’s interactive APIs such as drag-and-drop, Canvas,
Geolocation and more, technical writers will need to have a basic
understanding of JavaScript, which adds another potential layer of
skill requirements a technical writer must acquire (Samuels).
Many technical writers may also be attached to writing in document-
centric XHTML and therefor begrudge a transition to HTML5; however,
experts are now recommending a switch from XHTML to HTML5.
According to Peter Lubbers, “over 90% of XHTML is completely
broken.” Consequently, converters, like the DITA Open Tool Kit, that
generate XHTML output cannot open in Internet Explorer without
elaborate workarounds (Lubbers). Fortunately, HTML5 embraces
semantic style syntax and is also backwards compatible with XHTML
and older version of HTML. This means if technical writers are stuck in
their XHTML ways, HTML5 will be forgivingly accommodating.
HTML 3.2
XHTML 1.0
HTML 4.0
XHTML 1.1
HTML5
“To use the really
cool features, there’s
no way around it—
you need at least a
rudimentary
understand of
JavaScript.”
– Jacquie Samuels,
owner of Writing Wise.
FIGURE 10: HTML5 is backwards
compatible so that previous (X)HTML
pages can migrate to HTML5 more easily.

9
Conclusion
Conclusion:
With the recent Federal Communications Commission’s (FCC’s) Open
Internet ruling that broadband internet services are a public utility, there
has never been a more important time for technical writers to consider
what skills will support their ability to communicate in an age where the
internet is more ubiquitous than ever. Invariably, technical writers must
cultivate the skills and practices that will support the most versatile,
interactive, and accessible technologies the internet will support.
The first thing technical writers may need to consider is the cost of
implementing a web technology. While training technical writers in
HTML5 practices may be an expensive initial cost, a long-term
evaluation could prove that writing documentation in HTML5 is quicker
and easier than XHTML or older HTML standards, which could save
businesses significant labor costs overtime. In addition, although it may
make sense to use CMS plugins to support immediate documentation
needs, in the long run these CMS plugins may become outdated (such
as the Adobe Flash plugin), resulting in higher costs and time spent
building and maintaining information systems.
When considering responsive design and user experience, native
applications are probably the most significant counter argument to
HTML5 web applications, and it will be important for technical writers to
make a comprehensive analysis on what output modality will better
support their specific end-user and business needs. Nevertheless, if
technical writers want the largest possible audience to access their
documentation and still maintain quality user experiences, HTML5’s
innovative localization support, interactive features, and cross-platform
efficacy should make for a well-rounded and dependable candidate.
The W3C’s popular catch phrase “I’ve seen the future, and it’s in my browser,” makes a succinct
statement about the projection of a communication culture committed to the expansive connectivity
of the web. They stand by the new HTML5 standard as the catchall answer to better online functionality,
and it’s time for technical writers to log on and upload with the same level of innovative determination
in mind.
“So many things
pull in the direction
of HTML5 and
resisting it now
would be missing
the opportunity to
create great websites
that are capable of
mesmerizing the
visitors.”
– Vivek Ramen

10
Works Cited
Gardiner, David. "Picture This: Scalable Vector Graphics for Visual Documentation." STC Summit 2014.
Society for Technical Writing, 2014. Web. 15 May 2015.
Honomichl, Joshua. Personal Interview. 2 March 2015.
Lubbers, Peter, and Brian Albers. Pro HTML5 Programming. 2nd ed. New York: Apress, 2011. Print.
Lubbers, Peter. HTML5 and Its Impact on Technical Communication. ScriptoriumTech, 2012. Webcast. 31
March 30, 2015.
"Trends in Technical Communication, 2014 Edition - Scriptorium Publishing." Scriptorium Publishing. 21
Jan. 2014. Web. 30 Mar. 2015. <http://www.scriptorium.com/2014/01/trends-in-technical-
communication-2014-edition/>.
Ramen, Vivek. "10 Reasons Why HTML5 Implementation Should Happen Now." 10 Reasons Why HTML5
Implementation Should Happen Now. The Server Side, 8 Jan. 2015. Web. 30 Mar. 2015.
<http://www.theserverside.com/feature/10-reasons-why-HTML5-implementation-should-happen-now>.
Samuels, Jacquie. "Using HTML5: Do I Really Have To? | TechWhirl." TechWhirl. Tech Writer Today
Magazine, 24 July 2013. Web. 30 Mar. 2015. <http://techwhirl.com/using-html5-do-i-really-have-to/>.
Verna, Vikram. "TechComm Central by Adobe." TechComm Central by Adobe RSS. Adobe, 18 Jan.
2013. Web. 30 Mar. 2015. <http://blogs.adobe.com/techcomm/2013/01/html5-publishing-series-post-1-
why-you-should-publish-content-in-html5.html>.
Wilcox, Mark, and Christina Voskoglou. “State of the Developer Nation Q3 2014.” London: Vision Mobile,
2014. Print.

HTML5's Impact on Technical Documentation

Empfohlen

Empfohlen

Weitere ähnliche Inhalte

Ähnlich wie HTML5's Impact on Technical Documentation

Ähnlich wie HTML5's Impact on Technical Documentation (20)

HTML5's Impact on Technical Documentation