Monday, December 15, 2014

The Other Two CSS Books I Referenced in My STCTC Presentation on Dec. 9

Sorry for the delay in posting. I was doing a week of Flare consulting at a client in Houston and just got back to my office. Anyhow, the other two books that I suggested are:

  • The CSS Pocket Guide by Chris Casciano, Peachpit Press
  • Implementing Responsive Design by Chris Kadlec, New Riders

Wednesday, November 19, 2014

“Float” – CSS Feature and Symbol of Change

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 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 communication.

What’s “Float”

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 difference.

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 communication.

·         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 requirements appear.

·         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 design.

·         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 ( 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

Thanks to Allen Beebe, Cheryl Landes, and Deborah Sauer for their comments.

This post first appeared in the Society for Technical Communication's Intercom magazine (

Tuesday, October 14, 2014

Book On Responsive Design

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.

Sunday, July 20, 2014

Questions From My July 18 STC Webinar on CSS

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 its properties.

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 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 will be.

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.

Wednesday, June 11, 2014

Author! Author! With Flare

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.

The Tools

The tool kit consists of:

·         ·         Flare ( to write the content.

·         Amazon CreateSpace ( to convert the Flare output into a print book and put it up on Amazon.

·         Amazon Kindle Direct Publishing (, 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 confusion.)

·         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 Word output.

·         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 odd.

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 aesthetics.)

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.

Wednesday, February 5, 2014

Adobe RoboHelp 11 – A Review

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 Concepts

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, including:

·        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. Automatically…)

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 issues.

·        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 scratch.

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.

Other Changes

In addition to the two main features defined above, several others correct problems or omissions. These include:

·        Importing headers and footers when importing a Word document.

·        Defining different headers and footers in different master pages and applying them to different page types in print output.

·        A new color scheme for the interface for greater contrast and readability.

·        SWFs now display and play when included in Word output.


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 output.

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.