Ever since I started the Bleeding Edge session at the Society for Technical Communication Summit in 1999, I’m asked how quickly something new really emerges to affect technical communication. It doesn’t happen
that often but it does happen – Microsoft’s
introduction of HTML Help at the WinWriters conference in 1997 turned online
help in a new direction in an hour. This column discusses another such example
of change, the CSS “float” property. The float property’s impact won’t be as
quick or dramatic as that of HTML Help but I think that what it symbolizes for
tech comm is just as far-reaching.
The W3C introduced float in CSS1 in 1996. (See http://www.w3.org/TR/REC-CSS1/#floating-elements.)
But it remained little known in technical communication until responsive design,
promulgated in 2010, came to tech comm through help authoring tools in early
2014. In this column, I’ll briefly describe the float property’s function
before turning to the larger issue of what I think it symbolizes for technical
Float is a CSS property that lets us position elements on
HTML pages. No big deal, you say. We’ve done that for years using simple inserts.
True. What if we need multiple graphics side-by-side on a page? Again, no big
deal. Create a table, hide its row and cell borders, and insert the graphics in
adjacent cells in a row. Philosophically, using tables for page composition is wrong
but it’s worked fine for years. Until responsive design arrived.
Responsive design lets us create one (the crucial word) online output that automatically reformats
itself for the device on which it’s displayed. For example, say you have to
create online help to run on large-screen devices like desktops and laptops and
small screen devices like smartphones. You can create two outputs, each
designed for its target device. But now add support for 10” tablets? That’s
three outputs. Then 7” tablets? That’s four outputs. At some point, you won’t have
enough resources to create and maintain all your different outputs. Responsive
design solves this problem.
Responsive design lets you create one output that can detect
the properties of the device on which it’s displayed and tailor itself
accordingly. For example, three graphics laid out horizontally when displayed
on a large screen automatically shift to a vertical format as the screen gets
narrower. On the first screen below, I inserted the first group of three
graphics in a table. I inserted each graphic in the second group normally – not
in a table – but specified a left float for it. On a wide screen, there’s no
As the screen narrows however, like shrinking to tablet
size, the graphics in the table can’t shift because the table controls the layout.
The result is the horizontal scroll bar. But the graphics in the second group, controlled
by the float setting, automatically start shifting to a vertical format shown
in the next image.
As the screen narrows further, to smartphone screen size,
the graphics in the table still can’t shift but the second set of graphics,
controlled by the float setting, automatically shift to a full vertical format
as shown below.
Float also lets us move whole columns, change how text
aligns next to images, and more. This is what lets us create the “fluid grids”
that give responsive design much of its layout flexibility.
The float property can get very complex but it’s easy to
understand and apply for most online help and documentation projects. For
example, to get the graphics to behave as shown in the figures above, the code
is simply this:
Your help authoring tool’s stylesheet editor lets you add
the floats without getting into the actual code. You can start experimenting
with it now.
What’s the Symbolic Importance of
the “Float” Property?
Why spend an entire column on a little-known piece of CSS
code? In my opinion, float symbolizes four shifts taking place within technical
·Online superseding print – If you only output
print, float is irrelevant. But if you output print and online or online only, you should optimize your content for
online. Some techniques for doing so have been available to technical
communicators for years, like using relative size units (em, rem, or %) for
text rather than the familiar points, or embedding index entries. Float is the
latest such technique to reach us. The more you think “online” first, the more
in tune you’ll be with changes in technical communication.
·Growing interest in output to mobile – For
years, computer screens were so large that we rarely had to worry about screen
real estate. But growing interest in mobile as a single source output option
makes it increasingly important to find automated ways to use the same content on
different-sized screens. Programmatically-controlled layout modification
techniques like float do that and let us adapt quickly as new output
·HTML5 output – HTML5 output itself doesn’t need
floated graphics. But one of HTML5’s benefits is responsive design, and you’ll
want to look at using float to make the most effective use of responsive
·Increased development rigor – Poor development
practices like HTML tags with no end tags and tables created by using the tab
key to create columns have largely vanished as our authoring tools and
practices improved. Others, like local/inline formatting, are slowly vanishing
as more authors use styles. The result is that improvements in programming
practices are reaching increasingly esoteric areas like graphic positioning
control. We’ll never totally eliminate bad practices and “hacks” but we’ll minimize
them through techniques like float.
The symbolic effect of float is that it illustrates how web
coding practices are increasingly available to the technical communication
world. As technical communication moves away from “writing” and toward
“content” and the lines between web development and technical communication continue
to blur, techniques like “float” push technical communicators closer to web
developers, letting us future-proof our material and our jobs and get into
increasingly interesting work.
About the Author
Neil is president of Hyper/Word Services (www.hyperword.com) of Tewksbury, MA. He has 35 years of experience in technical
writing, with 29 in training, consulting, and developing for online formats and
tools including WinHelp, HTML Help, JavaHelp, CE Help, XML, RoboHelp, Flare,
and others now almost unknown. Neil is
MadCap-certified for Flare and Mimic, Adobe-certified for RoboHelp, and
Viziapps-certified for the ViziApps mobile app development platform. He is an
STC Fellow and the founder and manager of the Beyond the Bleeding Edge stem at
the STC summit. You can reach him at firstname.lastname@example.org.
Thanks to Allen Beebe, Cheryl Landes, and Deborah Sauer for
This post first appeared in the Society for Technical Communication's Intercom magazine (intercom.stc.org)
Per my presentation on responsive design at Lavacon on Monday, here are two books that I'd immediately recommend on responsive design and CSS.
- "Implementing Responsive Design" by Tim Kadlec, New Riders. Written more for programmers than help authors, but I'd recommend this book for the people at the presentation who were looking to go beyond what a help authoring tool can do through the GUI.
"The CSS Pocket Guide" by Chris Casciano, Peachpit Press. A easily digestible summary of the depths of the Cascading Style Sheet standard.
Mary C: Does RoboHelp provide a
basic CSS that one can adapt?
Yes. When you create a new RH project, RH automatically creates a basic
CSS called default.css. You can use this CSS and modify its properties, or (my
suggestion) copy it, save the copy with a name that ties it to the project or (better)
your company (in order to be able to apply it to multiple projects), and modify
Ellen C: Is it possible to create
unnumbered items in a numbered list in Word?
Yes, but there doesn’t seem to be a way to do that the way you would in
HTML and CSS (or else I couldn’t find it). To do so manually, press Shift/Enter
after a numbered item to add an unnumbered paragraph that keeps the indent and
doesn’t change the sequence of the next number. Keep pressing Shift/Enter to
add more unnumbered paragraphs. When you finish, press Enter to go back to
regular numbering style.
David M: What application do you
recommend to create a CSS?
It depends. Do you want to create a CSS for a project
done in an authoring tool or do you want to create a CSS independently of any
project or tool? Email me at email@example.com
to let me know and we can discuss from there.
Suzanne S: I'm currently using
RH10 and we will be upgrading to RH11 for responsive design. Fonts and margins
are currently defined in point sizes. To make the output work, do we need to
make modifications to the style sheet to use relative size units?
The more you use relative size units the better the responsive design
Barbara: I took over a project
with many tags with the style within each tag. I have
changed this by adding classes like p
class=BodyText" and so on. Is this not correct?
You’re correct. The fewer the sub-classes the better, but you
definitely want to replace inline formatting with sub-classes.
Ever wanted to write a book that people can buy on Amazon? Perhaps
a technical book, perhaps a book of family history, or anything in between.
In this post, I’ll discuss how to do that using MadCap Flare
as part of a larger tool kit that lets you publish a book to Amazon in both
print and ebook format at mind-bogging speed.
By way of background, I’ve written seven books in my career.
The “Small Business Guide to Computers & Office Automation: A Comprehensive
Overview of Computers and Modern Office Technology, and How to Select a System”,
was published in 1985 by Knowledge Industry Publications. The second, an update
of the office automation book, was published by an in-house press in 1989. The
original book took about five months to write and almost as long to publish.
The slow publication process made it hard to write a technical book because it
was almost impossible to update the book once it entered the process even though the subject matter itself might be changing. And so I
stopped writing commercial books.
Then, in 2010, two things happened.
First, the late Nan Fritz, president of nSight, a consulting
company in Burlington, MA, said “Neil, you’re a consultant. You have to write a
book.” I decided she was right and,
after some thought, decided to take a MadCap Mimic course that I’d written
several years earlier and repurpose it in book form. That meant that most of
the writing was already done, in Word format.
Second, I found a blog post, now lost, that discussed why
consultants should write books and why and how to self-publish. The gist of
that post was that while it was prestigious to have a “real” publisher, the
process was slow, publishers paid low commissions and no advance, and provided minimal
marketing support. Self-publishing and “print on demand” technology made it possible
to write a book and make it available on Amazon quickly and inexpensively but with
a higher commission rate. There was still no advance and you were on your own
for marketing, but that was like working through a real publisher anyway.
So I tried it. In the process, I put together a tool kit and
workflow that I’ve used to write five books since 2011, all available on Amazon
(blatant sales pitch warning). The books are “Essentials of MadCap Mimic 6”, “
Advanced and Unfamiliar Features in MadCap Flare 8”, “Advanced and Unfamiliar
Features in MadCap Flare 9”, “Advanced Features in MadCap Flare 10”, and
“Creating Mobile Apps Without Coding”. In the rest of this post, I’ll explain
the tools, the workflow, and point out some lessons learned.
·Amazon CreateSpace (www.createspace.com) to convert the Flare
output into a print book and put it up on Amazon.
·Amazon Kindle Direct Publishing (https://kdp.amazon.com/), also known as KDP, to convert CreateSpace’s
print output to Kindle format and put it up on Amazon.
The Workflow - Flare
The most efficient writing workflow was to treat the book
like any Flare project. I also planned from the start to write multiple books
using the same basic Flare settings, so I initially set up the page layout, CSS,
and one table CSS for the Mimic book with a view toward reusing them.
·I set up the page layout using a custom size
(6”x9”) and default 1” margins. (I used Flare’s 6”x9” because that was the CreateSpace
size that I planned to use for the printed book and matching the sizes from the
start meant fewer reformatting problems when publishing.) I added the book name
in the header block and the “page n of N” page numbering template in the footer
and that was that for the page layout. I could now re-use the page layout in
multiple books by copying the flpgl file from project to project and simply changing
the book name in the header.
·I set up a simple CSS, specifying h1, h2, h3, p
(paragraph), Note, Tip, and Caution styles. I made all the settings in the
default medium, then switched to and used the print medium. (Why not make all
the settings directly in the print medium, since that was the medium I was
going to use anyway? Most of my Flare work involves online outputs using the
default medium and if I used the print medium as the “default” for the books, there
was a risk of getting confused between mediums. Not as efficient an approach as
simply designating the print medium as the default but with less risk of
·I set up a very simple, black and white-oriented
table CSS to ensure simple printing.
For each new book then, the overall workflow was this:
1.Create the new project in Flare with MS Word as
the primary target. (All the file conversions to print and Kindle take place in
CreateSpace and KDP, not Flare.)
2.Created the outline in Flare, with each section
in the outline being a topic.
3.Imported the page layout, stylesheet, and table
stylesheet, making sure to change the heading in the page layout to the new book
title. (I forgot to do that once and wound up generating a proof (final review)
copy of the Flare 8 book that was perfect except that it used the Mimic title
in the heading. A silly mistake but easy to fix.)
4.Created a target called “ Word”
and made it the primary target.
5.On the XML Editor toolbar, set the Layout and
Medium options to Print. (This may sound like a lot of work so far, but most of
it was one-time for the first book. I could then copy those files to the new
book project. The book-specific work took minutes.) I then started writing.
Several things to be aware of as you write:
·Bullets work fine in the print output generated by
CreateSpace but not in the Kindle output generated by KDP. This is a problem if
you’re writing a technical book because bullets are so common. You’ll have to
find a workaround, such as changing your wording or indenting “bulleted” paragraphs.
·Watch your word spacing. In several cases, Flare
inserted two spaces before a word but only showed one space until I saw the
·MadCap Capture works well for capturing screens
and inserting them in topics. (You can use any screen capture tool. However,
don’t draw highlight boxes on screen shots because the area within the
highlight box will become opaque in CreateSpace.)
·Set the h1 style’s page-break-before property
(in the PrintSupport group on the Stylesheet editor) to Always to avoid having
a main heading at the bottom of a page and the text on the next page. However,
if you have two short topics that both start with h1, you can wind up with two
facing pages that are mostly empty and have to close up those two headings in Word.
·Rewrite your material to avoid having a
paragraph that ends with a short line that runs onto the succeeding page. If
this happens, you may wind up with a left-facing page that contains a single
word and the next topic starting on the right-facing page. This is fine but looks
The table of contents can take some finagling depending on
the structure you want. There are too many options to cover in one blog post, so
I’ll put out an open offer to answer any questions down the road.
When you’re done, generate the Word output. Two things to
watch out for when you do:
·On the Advanced tab of the Target editor in
Flare 10, select Generate TOC Proxy and Generate Index Proxy in the Output
Options group. (You can also select Generate Glossary Proxy if you created glossary
entries.) If you have an older version of Flare, you can generate the TOC and
Index but you’ll have to do so using special-purpose topics. See the help or my
Advanced Features… book.
·On the Advanced tab of the Target editor in
Flare 10 or before, select the Embed Images in Output option in the MS Word
Output options group.
You can now review the Word file to make sure everything is right.
If you need to change the content, you can make the change in Flare and
re-generate the Word output or make the change in the Word output and
separately in Flare. Also check for bad page formatting, such as having one line
in the last paragraph of a topic on a separate left-facing page. When you’re
satisfied, you’re done with Flare and ready to move into CreateSpace.
The Workflow – CreateSpace
CreateSpace is a book production, pricing, and distribution tool.
It lets you set up your print book’s page size, color, and cover, plus distribution
and pricing options for various Amazon channels. The process is step-by-step
and you can perform all these tasks for free or pay for professional support. I
did it myself and, while the results might have been better if I used the
support, I thought they were good enough. (Part of the decision between
do-it-yourself versus using a designer is the choice between time-to-market and
When you finish laying out the book, including checking the
layout in a page simulator, you can check a virtual copy or a printed proof
copy. I recommend using the printed proof for two reasons. First, there’s just different feel between holding something tangible versus virtual. Second, you’ll
want to see how your images look. (My main problem has been that the pixel
density of my images is lower than CreateSpace prefers. CreateSpace will
complain but let you ignore the problem. By getting the printed proof copy, I
can make sure that the images really are okay.) Once you’re done, you submit
the book for final review by CreateSpace.
After you fix or ignore any problems that CreateSpace identified,
you give CreateSpace the go-ahead to put the book up on Amazon. CreateSpace
will then slide you into KDP.
The Workflow – KDP
KDP is the ebook side of CreateSpace. KDP will take the
files from the CreateSpace work and use them for the Kindle output. The process
is almost effortless.
Two Obvious Questions
The first question is how long the whole process will take.
The writing part, in Flare, is up to you. Depending on how
well you know the material, you might write the book in six months or, as I did
for the Flare 10 book update, about a month.
The real time saving is on the publishing side with
CreateSpace and KDP. The first time I did this, for the Mimic book, I worked
slowly and thoroughly and the entire process took eight hours! (As opposed to
nearly five months.) My book was on Amazon in print form and Kindle form the
next day. As spectacular as I thought this was at the time, the publishing
process for my latest book, “Advanced Features in MadCap Flare 10”, took an
hour and a half! I ran through the process in the morning, the print version
was on Amazon that afternoon, and the Kindle version the next morning.
This speed has totally changed how I write books. I can now
write a book and time it for release with the software it’s describing without
having to factor in months of lost time for production.
The second question is why not write the book directly in Word
rather than write in Flare and output to Word? There are two answers. First,
I’m a MadCap certified Flare trainer and consultant, so it made sense for me to
explore what Flare can do. More relevant is the fact that Flare’s control
files, especially the CSS, table CSS, and page layout, provide a rigorous but almost
invisible degree of control as I write. For example, by making the CSS the
master CSS for the project, my content formatting takes place automatically. Basically,
it’s a snap to set up the infrastructure of a new book, with better control than
Word and without the quirks.
Writing a book will never be easy. But using Flare in
conjunction with CreateSpace and KDP means that the writing phase is better
controlled and the publishing phase is so quick as to be almost irrelevant in
your planning. Try it. You’ll like it. I did.
RoboHelp was one of the first HATs (help authoring tools)
and has long had a big part in molding today’s online help and content world.
Adobe acquired RoboHelp in 2005 as part of its purchase of Macromedia and has
been extending it since then, starting with v. 6 in 2007 and continuing through
v. 11, released on January 14, 2014.
In this review, I’ll focus on what I consider to be the most
significant features of RoboHelp 11 and what they say about trends in tech
comm. There are two, enhanced support for responsive design as part of HTML5
publishing, and the cloud-based collaboration added to the Resource Manager.
HTML5 Publishing and Responsive Design
I’ll start with a quick overview of HTML5 and responsive
design if you’re not familiar with the terms.
HTML5 is the successor to XML and earlier versions of HTML. It’s
both a coding language and an output format. RoboHelp 11 still uses XHTML,
introduced in v. 8, as the native coding environment, but added HTML5 as a browser-based
output format in v. 10 and extended it in v. 11. You can still use WebHelp for browser-based outputs, but HTML5 has
several benefits that make it worth looking at as a replacement for WebHelp,
·Searchability by web crawlers. The WebHelp
output format has met our needs for years but has a problem that didn’t
manifest itself until web search crawlers came into use. WebHelp uses “framesets”
to controls layout, but framesets block web crawlers from going beyond the home
page in browser-based help. The result is that the online help that you write
and distribute as WebHelp won’t be found by a crawler and won’t appear in the
list of hits from a Google search. In other words, users can’t find your content through Google. This may
not matter if the content is behind a firewall or login and only available to
customers. But if your company is adopting a more public-facing strategy, this
can be a strategic limitation. HTML5 fixes that limitation.
·Support for CSS3. This extension of the CSS
(Cascading Style Sheet) 2 standard gives more power and flexibility for
formatting under modern browsers.
·Support for a new type of mobile apps called
“hybrid apps” that are based, in part, on HTML5. RoboHelp doesn’t output hybrid
apps, but the HTML5 code that it does
output forms part of the foundation for those apps. In other words, HTML5
output is a step toward hybrid apps.
Responsive Design Concepts
The idea for responsive design arose as more and more
devices with different screen sizes, resolutions, and other properties appeared
on the market. We can optimize our
outputs for one or two devices, but it quickly becomes technically difficult
and cost-prohibitive to optimize our outputs for every device on which they might
appear. The emerging answer is “responsive design”.
Responsive design says that content can automatically change
its design based on the properties of the device on which it’s displayed – e.g.
it’s device-agnostic. For example, HTML5 output from a project can change its
design depending on whether it’s displayed on a PC, tablet, or smartphone. (The
image below shows how content might reformat itself based on the device. The
three images look the same at first glance, but note how the Greek temple, the Adobe
icon, and the controls move or disappear depending on the output.
RoboHelp’s Support for HTML5 Output and Responsive Design
RoboHelp 10 supported what Adobe called “Multiscreen HTML5”
– basically responsive design. It used “screen profiles” (to specify different
screen resolutions that controlled the redesign), “screen layouts” (to design
the page types and customize them for the different resolutions, and CSS “media
queries” (to define the specifics of the page format for each resolution set
through the screen profiles). This mix of features let you automatically change
the design of the output and, by using conditional build tags, change the
content itself depending on the device. It was a good start, but there were two
·Some of the concepts, particularly CSS media
queries, were new to many users.
·Some of the work, especially screen layout
design, was complex and could be time-consuming.
RoboHelp 11 goes a long way toward addressing both issues by
adding a new output type, Responsive HTML5. Responsive HTML5 is a streamlined
version of Multiscreen HTML5 that uses predefined layouts for different screen
sizes and properties. In other words, much of the setup work has been done for
you. If you do want to customize a
layout, the process is semi-wizard-driven. To contrast the two approaches, the image
below shows the layout editor for the Topic page type in Multiscreen HTML5.
There’s a lot of power available in the toolbar but you have
to know what you’re doing. In contrast, the image below shows the layout
customization editor for a layout, in this case the Theme2_Government layout,
for the Responsive HTML5.
The many screens prompts make it easy to see what screen object
you’re changing and the options are clearly labeled in the Properties pane. So
customization will be fairly straightforward, hopefully tasteful as well. And
Adobe has a link to a layout gallery which currently lists two predefined
themes, with more sure to come, so you won’t have to start creating yours from
So Responsive HTML5 is easier than Multiscreen HTML5 but
less customizable. The main difference is that Multiscreen HTML5 lets you use conditional
build tags to vary the content for individual devices while Responsive HTML5 lets
you use conditional build tags but applies the same build tagged content for
all devices. This should be a minor point if you want to output the same
content to all devices, but may affect your planning if you literally want
different content output to a tablet versus a smartphone.
If all this sounds confusing, here’s a simple summary. If
you want to output a project using responsive design, open the project in
RoboHelp 11, select Responsive HTML5 output in the Single Source Layouts pod,
select the desired layout on the General tab, and generate. When RoboHelp
finishes generating, click the View Result button (and allow blocked content if
you use IE). The output displays in a browser window. Now grab a corner of the
browser window and start reducing its size. Once you get to certain sizes – think
tablet and smartphone – you’ll see the format change automatically. You’ll have
to think about the actual design but the sheer mechanics are impressively
simple. And it’s just neat to watch.
Cloud-Based Collaboration via Resource Manager
I’ll start off with a quick overview of the Resource Manager
if you’re not familiar with this feature.
Adobe added the Resource Manager several versions ago as a
way to share files between projects. For example, let’s say you want to use the
same CSS in two projects. The old approach was to find the desired file in the
“master” project’s folder in Windows Explorer and copy it to the other project.
This worked, but you were doing the file “sharing” manually, outside RoboHelp,
so it was easy to paste the copy of the file-to-be-shared in the wrong folder.
The Resource Manager eliminates this problem. You’re sharing
the files in RoboHelp under RoboHelp’s control, so they’ll automatically be put
in the correct folder.
The one thing missing in this scenario was file sharing via the
cloud. RoboHelp 11 fixes this by letting you set up a shared location using
various popular cloud-based services rather than a network drive. You’ll see
this option in the Location Type field on the Add Shared Location dialog box
that displays when you click on the Add Shared Location icon on the Resource
Manager pane, shown in the image below.
You can select from Dropbox, Google Drive, SkyDrive, or
others that you might use. When you select one, RoboHelp will find its folder on
your PC and fill in the Path field for you. You can also set up subfolders
within a service and select just that subfolder. Once set up, you can share
topics (new in v. 11 – previous versions didn’t let you share topics) and
various control files. If a topic contains embedded elements such as images,
RoboHelp will detect their use and carry them over with the topic. (You will
have to pull in any snippets separately, but RoboHelp will add them to the
topic once you do.) There are also various ways to synchronize changed files.
Overall, the cloud-based collaboration feature is a useful
extension of the file sharing concept behind the Resource Manager and a
reflection of changes in tech comm.
In addition to the two main features defined above, several
others correct problems or omissions. These include:
·Importing headers and footers when importing a
·Defining different headers and footers in
different master pages and applying them to different page types in print
·A new color scheme for the interface for greater
contrast and readability.
·SWFs now display and play when included in Word
RoboHelp 11 will be largely familiar and easy to learn for any
user of an older version. The biggest new convenience is the addition of
cloud-based collaboration, but even that fits into Resource Manager.
The most important new feature, in my opinion, is the
addition of the Responsive HTML5 output. Few of my RoboHelp clients need mobile
or display-agnosticism yet but every one I’ve spoken with sees it as on the
horizon. Responsive HTML5 makes it easy for them to get their feet wet in
mobile and should help them ease into the full power of the Multiscreen HTML5
Do you need to upgrade to v. 11? If you don’t need
responsive design, cloud-based collaboration, or multiple headers and footers
in your print output, probably not. But if mobile or display-agnosticism is on
your horizon, RoboHelp 11 is a worthwhile upgrade and a job well-done by Adobe.