Tuesday, December 21, 2010

W3C Mobile Web Best Practices and HAT-Based Mobile – Part 12

Four separate but closely related recommendations regarding any text entry…

5. [URIs] – Keep the URIs of site entry points short.

54. [MINIMIZE KEYSTROKES] – Keep the number of keystrokes to a minimum.

55. [AVOID FREE TEXT] – Avoid free text entry where possible.

56. [PROVIDE DETAULTS] – Provide pre-selected default values where possible.

The gist of these points is that it’s hard to type on a mobile device keyboard, whether real or virtual. Mobile device users text like mad so it’s certainly possible, but if you have big hands or are in unstable environments, you’re likely to have problems typing. This is true especially where accuracy is important, such as typing URLs as opposed to text. (Speaking from experience with my latest smartphone, a Samsung Captivate with a large virtual keyboard, I still have to tap the keys with a fingernail and watch what I type very carefully.)

What this suggests is eliminating any free text entry if possible, and minimizing the rest. More specifically, with regard to the four points above…

Minimize the length of any URI that viewers have to type. The W3C recommends setting up any target web sites so that viewers can access them without having to type a sub-domain as part of the URI. For example, rather than requiring users to type this:


Let them type:


The “www.’ portion isn’t hard, and many mobile device keyboards have pre-set “www.” keys anyway. It’s more the length of what follows the www, such as:


One easy, albeit tedious step, is to run URLs through a URL compressor like TinyURL, www.tinyurl.com. For example, it compressed the long and hard-to-type URL above from 56 characters to 26, as shown below:


It’s still no treat to type, but there less of it. And if you can replace the typing of URIs with pre-defined links, so much the better.

More to come…

Tuesday, December 7, 2010

W3C Mobile Web Best Practices and HAT-Based Mobile – Part 11

A recommendation regarding graphics…

25. [LARGE GRAPHICS] – Do not use images that cannot be rendered by the device. Avoid large or high resolution images except where critical information would otherwise be lost.

Whether to show graphics has always been a design issue in online help/doc, but one graphics issue that hasn’t been a problem until now is size. Desktop and laptop displays are large enough to show all but the largest graphics; the few that were too large usually needed just minimal scrolling. This ease of use often leads authors to add graphics with abandon. However…

Mobile device screens, except perhaps those on iPads, are so tiny that all but the smallest graphics require scrolling. And there doesn’t seem to be any good technical solution; the solution is information management – re-examine our projects to see if the graphics are really necessary and:

• If a graphic is not necessary, delete it.

• If a graphic is necessary, try to crop it to eliminate extraneous information and focus on just the salient portion.

• If the entire graphic is necessary, see if it can be scaled down.

• If scaling fails because the result is too small to read, accept the idea that some content just may not fit your design but still has to be included because the content is more important than the design.

• If a graphic works on large-screen devices and is nice to have, but causes design and usability problems on mobile devices, you can use conditionality to flag and exclude that graphic from mobile outputs. This is just one more way to use the conditionality feature in our help authoring tools.

MadCap Flare does offer one partial technical solution – the thumbnail attribute for the img tag. This feature lets authors display a graphic as a thumbnail until viewers click on or hover over the image, at which point it expands to a pre-defined size. It’s a nice way to insert graphics in topics but minimize their space requirements until viewers want to see them. However, the hover or popup display effect converts to a jump link in Flare’s mobile output, presumably because MadCap could not be sure if a particular mobile device supported hover or popup – presumably none did at the time – and so converted the thumbnail display effect to a safe, regular jump link.

• If you must include an entire, large graphic, you might use image maps to link areas of the graphic to other pages that offer more detail. But many mobile devices don’t support image maps. Those that do may not offer any way to reach a hotspot except by using the up, down, left, or right movement function. This type of movement works but is tedious if you need to reach a hotspot far down on a hotspot-rich image map.

• It is also possible to eliminate the whole too-large-graphic issue by simply including the graphic at whatever size is necessary and zooming the display. The problem with this approach, however, is that it re-introduces horizontal and vertical scrolling.

(I’ve often wondered why virtual reality glasses never took off since they solve the whole problem of limited screen size. But they haven’t.)

So the best way to deal with large graphics on mobile devices is to re-evaluate the content to see if those graphics, or any graphics, are really needed, get rid of those that aren’t, modify those that are, and accept the result. This may take a lot of work in large projects. But bear in mind that if you’re going to output your online help/doc to mobile, you may be doing so many other “clean-up” steps, such as eliminating hard returns between paragraphs or changing CSS size settings to relative units, that re-evaluating graphics may be just one more task in the shift to mobile.

More to come…

Wednesday, November 24, 2010

W3C Mobile Web Best Practices and HAT-Based Mobile – Part 10

A recommendation regarding terse markup…

45. [MINIMIZE] – Use terse, efficient markup.

I noted in part 9 that the desktops and laptops for which we create online content have so much power that we often code verbosely and inefficiently because we can. And it’s less work. I was referring to style sheets there, but the same point is true for markup in topics.

The issue of terse, efficient markup falls into several areas. In each case, we have to ask whether the benefit is worth the effort.

Redundant White Space

One area, according to the W3C, is that “content …marked up in… XML can… be made smaller while preserving… semantics by removal of redundant white space (i.e. spaces and new lines).” It isn’t clear, but I think what the W3C is referring to is white space and new lines in code view, not WYSIWYG, but there is an efficiency issue in WYSIWYG too so I’ll look at that as well.

Code View – “Pretty Printing”

The W3C suggests avoiding “pretty printing,” the formatting of markup with indentation, because it “can generate large amounts of white space and… add to page weight.” But it also notes that “pretty printing” may be an important part of the authoring, in which case “try to arrange that redundant white space is stripped when serving a page.” It further notes that “…some network proxies strip white space that they think is redundant, [but] not all do so, so… not… to rely upon this behavior.” What is this about?

Look at a topic in code view in your authoring tool. You’ll see something like this:

Note the indentation and new lines, all of which add space. For example, the code above uses 194 bytes. Collapsing the indents to look like this:

reduces the size to 184 bytes, a 5.1% drop. And this:

reduces it to 172 bytes. So eliminating the indentation and white space reduces the size of the file from 194 bytes, or 11.3%. (Your numbers will differ.) This may seem trivial, but smaller files reduce network traffic load. However, the increased terseness and efficiency of the markup also makes the code less readable. The first example is easier to read than the second and certainly the third.

This may force you to weigh the need to work at the code level versus code efficiency. If code efficiency is most important, you’d buy the most efficient authoring tool you can and make it a policy not to work in code except in unusual cases. Conversely, if you want to be able to work in code, you may go with a tool that creates less efficient markup. Talk to Engineering or IT about this.


HTML and XHTML collapse multiple character spaces, so we can’t use multiple spaces to indent text. However, one thing we often do is add a line space between paragraphs, a bad habit left over from our word-processing days, rather than adding a “space after” or bottom-margin property to Normal and other body-content related styles. Does doing so reduce file size? Based on a rough test, yes.

I created a topic with five lines of text, effectively paragraphs, in Normal style, with one line space after each paragraph and a bottom margin of 0 in Normal style. The file size was 630 bytes. When I set the bottom margin to 1.12 em in Normal style and deleted the line spaces, the file size dropped to 538 bytes, a 14.6% drop. (Again, your numbers will differ.)

I always suggest that clients and attendees in training classes set paragraph spacing using a top and bottom margin setting for the Normal style in the CSS simply because the more we control through the CSS rather than by local formatting, the more future-proofed our content is. A file size reduction of this magnitude is just one more reason to get rid of hard line spaces between paragraphs.

Excess Code

We may also find that our topics contain additional, proprietary codes. Some are inserted by our help authoring tool to add custom features. Others may appear in topics created by importing Word files into the help authoring tool. These extra codes increase the file size. It is worth trying to get rid of them?

If we plan to keep our current authoring tool, then any proprietary code can probably stay in the file, even if the code is inelegant. However, this can be risky if we’ve been using a particular tool for years and take the proprietary codes for granted, only to learn that they don’t convert well when we change tools or formats and must be fixed by hand. Because of that, it’s a good idea to periodically review a sample of topic files created by our tools and check the codes to see what’s standard and non-standard.

A similar problem occurs in topics created by importing Word files. The files often have Word-specific code that may not harm the topics but do increase their file sizes. And it is possible that those Word-specific codes might cause trouble during some conversion in the future. So, again, it’s a good idea to periodically review a sample of topics created from Word files and check the codes to see what’s standard and non-standard. I don’t know of any specific references for this, but I recently read a book called ePub Straight to the Point by Elizabeth Castro, published by Peachpit Press in 2011, that discusses how to convert Word files to ePub format. In the discussion, Castro explains what many of the Word codes are and how to delete them. I don’t think it’s the complete answer but it is worth a look.

The big problem in deleting excess, proprietary code added by an authoring tool or Word is simply the greater knowledge required to do so and the risk of breaking something. So while eliminating these codes may increase terseness and efficiency and reduce file size, it seems like the most difficult part of the job and one to be approached very carefully and after some experimentation.

More to come…

Monday, November 22, 2010

W3C Mobile Web Best Practices and HAT-Based Mobile – Part 9

A recommendation regarding style sheet efficiency…

44. [STYLE SHEETS SIZE] – Keep style sheets small.

The desktops and laptops for which we create online content have so much power that we often code inefficiently because we can get away with it, and it’s less work than coding efficiently. But mobile devices lack the power and resources of desktops and laptops, so they force us toward more optimized control files.

One of the most important of those files is the CSS, and one issue is whether our target mobile devices support CSS caching… After a device has retrieved the CSS for a topic, will it store that CSS to use for the next topic or does it have to retrieve the CSS again for the next topic? If so, we want to keep the CSS small to use minimal device resources. If the device does not support caching, it may have to retrieve the CSS for each topic. If so, we still want the CSS small to reduce network traffic for the repeated downloads of the CSS for each topic.

The W3C notes several ways to keep CSSs small but the simplest is to “…optimize style information so that only styles that are used are included.” How does this apply to help?

When our help authoring tools create style sheets, they include a default set of styles, like heads 1 - 6. The problem is that we often accept that set of default styles, even though we never use some of them in our topics. Those unused styles simply make our CSSs larger to no purpose. The solution is to remove the unused styles from the CSS. How?

We can easily remove unused styles through the authoring tool interface. But how do we know if those styles are really unused? Even if we keep careful records of style usage, it’s difficult to be sure - especially when dealing with legacy projects or large projects that we’re not totally familiar with.

A better idea is to search for the style codes in the topic code. Use the authoring tool’s multi-file search feature to look for the questionable codes within all the topics in the project. If the search doesn’t find any hits, then delete the style code from the CSS. This is a sure-fire approach technically, but it can be slow and tedious to work your way through a large and complex CSS or one that you have not checked for a while.

So the best solution here isn’t technical but managerial. Create a standard CSS for all authors to use, do one search pass through your legacy topics to clean up the style codes they contain, and prohibit ad hoc modification of the CSS after that. It’s one more argument in favor of standards.

More to come…

Thursday, November 11, 2010

W3C Mobile Web Best Practices and HAT-Based Mobile – Part 8

Another recommendation regarding formatting.

41. [MEASURES] – Do not use pixel measures and do not use absolute units in markup language attribute values and style sheet property values.

I discussed absolute vs. relative units in part 2 in relation to scrolling, but I’ll define this issue again here and expand on it.

From my consulting and training experience, I find that authors usually define the size of fonts and spacing in points, such as 10pt for Normal text. Two reasons for this:

• Many help authoring tools, like RoboHelp, use points as the default so we’ve just gotten used to it.

• For authors who come from hard-copy, especially Word, points is the default and an easily visualized unit – 1 point = 1/72”, so 12 points = 1/6”…, for example

But when we put content online, absolute units like points cause trouble for two reasons.

• Different display technologies may render points differently. For example, 10 pt is standard for Normal text on PC displays but too small on Macs because of the different technologies. So if you’re creating online material that might be read on PCs and Macs, you’d need two CSSs, one for each, with two different sizes for Normal text.

This isn’t a problem if you create online content for local use on one platform, such as HTML Help on PCs. But if you have to convert that content to a format like WebHelp that might sit on a server and be accessed by users with different platforms, like PCs and Macs, this does become a problem.

• Browsers can’t resize point-based text.

Going relative fixes these problems easily, once you get used to thinking in this new way. Relative units replace points, pixels, inches, etc., with units like % or ems. The benefit of relative units is that they automatically adapt, under the browser’s control, to the space on a given display.

For example, a graphic that’s 180 pixels wide might be fine on a standard display but too wide for a mobile device, so the device adds a horizontal scroll bar. Horizontal scrolling isn’t evil, but it does reduce usability, especially if you have to scroll vertically and horizontally, so you want to avoid it where possible.

Setting the width to 100% fixes the problem. This says that the graphic should display at 100% of the available space and leaves it up to the browser to figure out what that is.

This approach isn’t perfect. It’s possible to apply relative size to a graphic which displays it correctly but makes it too small to read. Or it may not display correctly in certain cases, such as within table cells in ePub format running in the Adobe Digital Editions (ADE) viewer. Still trying to track this one down…

What relative units can you use? There are several, including %, ems, and exes. The % is relative to the size of Normal style at 100% on any browser. So, for example, setting h1 style to 150% says that all heading 1 text should be half again as large as Normal text on each browser. (This isn’t exactly the case, but it’s close enough to get a mental picture.) The em is based on the baseline height of the m on the browser. The ex is similar to the em but based on the x.

Of these three, the most widely supported (a totally unscientific statement based solely on experience) are % and em. Some people prefer the em. Others, myself included, prefer the % because it’s easier to picture mentally. Pick the one that makes the most sense for you and is easiest to use.

Next, keeping style sheets small and using terse, efficient markup…

Wednesday, November 3, 2010

W3C Mobile Web Best Practices and HAT-Based Mobile – Part 7

Several inter-related recommendations regarding content formatting.

53. [FONTS] – Do not rely on support of font related styling.

Per the W3C – “Mobile devices often have few fonts and limited support for font sizes and effects (bold, italic, etc). …use of font size, face, or effect, for example to highlight an answer or a stressed word may not achieve the desired result.”

This seems obvious. So how does it affect tech comm?

If you’re creating “true” mobile apps, they may have little or no font related styling since you’ll be creating the apps from scratch and thus, hopefully, following best practices. But if you’re mobilizing an existing online doc or help project, it may have lots of font related styling, bold or italics, because it was created at a time when styles and style sheets didn’t have the importance they do now. Those font related styles in your material can affect your project planning, development style, and development process.

1. You have to find out if the devices you’re publishing to can support font related styling. If so, the styling becomes a best practices issue instead of an immediate programming crisis. But even if it’s not a crisis, font related styling, essentially local formatting, is still bad practice in an increasingly single sourced world and will affect your projects eventually. And if any of your target devices don’t support font related styling, you’ll have to deal with it now. To do so…

2. You have to get rid of it. This isn’t difficult but it is tedious, especially if there’s a lot to get rid of. You may have to do large-scale search and replaces in the code to replace local formatting with character styles. This works but it’s scary, even if you’ve backed up the project. More difficult still…

3. You have to stop using font related styling, possibly a major change in how you work. It’s simple mechanically – add bold and italic character styles to the project CSS. What’s hard is breaking old work habits, no longer using the text formatting toolbar in Flare or RoboHelp, for example. This can be surprisingly difficult.

So if font related styling is now off the table, how do we format text?

42. [STYLE SHEETS USE] – Use style sheets to control layout and presentation, unless the device is known not to support them.

Style sheet, or CSS, use has been growing in tech comm for years but still isn’t as widely or consistently used as it should be. CSS styles are used on heads and body content in online help and doc, but less often for things like bulleted or numbered lists, tables, notes, cautions, etc. More rarely still are CSS styles used for text enhancement, again because the text formatting toolbar is so convenient. Some authors are also deterred by the need to create a separate CSS for each target mobile device. (This isn’t necessary – instead, the solution is the media types feature in the W3C’s CSS spec, MadCap Flare’s “mediums”, but this feature is still not that widely known.) There’s also uncertainty in some Word shops about the distinction between how styles work in Word vs. in HTML/XHTML.

The upshot? Any doc group that sees single sourcing to mobile in its future should plan to train all authors on the concepts and use of style sheets and new development processes so as to reduce or even eliminate local formatting.

There’s more to this issue as well, including:

• The need to organize documents so that they can be read without style sheets if a particular mobile device doesn’t support them.

• Editing style sheets to minimize their file size.

• Using relative measures in place of absolute measures like pixels and points.

To be covered in the next installment…

Tuesday, October 26, 2010

A Few More Questions From Last Week's CSS Class...

Overlooked a few...

Q. If you create a custom style, like Note in the exercise, and set a background color for it, how do you narrow the style so that it does not run from the left border to the right border but instead looks more like a colored box?

A. Select the style in the Stylesheet Editor, open the Box properties group, and set the margins using the Margin-right and Margin-left properties.

Q. If you've applied a character format from the style sheet, such as applying the bold style from the Styles pane, how do you turn off that formatting and go back to plain text?

A. This changed a bit in Flare 6 from earlier versions, so you can't right-click on the formatted text and select Unbind on the popup menu. Instead, double-click on the formatted text to highlight it, then click on the formatted text once more, then right-click on it and select Unbind on the popup menu.

Q. How to control the alignment of hanging indents like bulleted or numbered lists?

A. Use the Margin-left property in the Box properties group on the Stylesheet Editor.

This time, I really think that's it...

Monday, October 25, 2010

Responses to Questions From Last Week's Remote Flare CSS Class


I think this should take care of the remaining questions from last week's CSS class. If it does not, please email me directly:

From AS:

1. Is there a feature in table styles or style sheets that could be set so table rows NEVER break across a page? (In Author-It we currently select all our table rows in a table, and simply click an icon that applies this option.)

Try this - in the Stylesheet editor, select the TD style, open the PrintSupport property group, open the Page-Break-Inside property, and select Avoid.

2. Is there a way to control orphans or widows other than by "lines"? Currently we are monitoring these in print very manually because we want to keep entire paragraphs and/or list items together. So when we output to print (Word) we go through the entire document, and for any such situations we have to select the text, choose Paragraph Properties > Keep with Next.

No. This is apparently limited to "lines" as units, per the CSS spec according to tech support.

From JK:

Sometimes when I am working on a topic page I will get these blank open spaces between my heading and paragraph blocks. Do you know what causes the blank open spaces and how to remove them?

Check the margin settings on the offending style, the h6 in your example. If that's not the problem, look for another head style above or below the offending style, as in the h1 above the h6 in your example, and check ITS margins.

Two of you had very specific questions that I'll address individually. Aside from those, I think this is it. Nice working with you all.


W3C Mobile Web Best Practices and HAT-Based Mobile – Part 6

Two recommendations related to the “size” of a “page”, or topic.

20. [PAGE SIZE USABLE] – Divide pages into usable but limited size portions.

21. [PAGE SIZE LIMIT] – Ensure that the overall size of [the] page is appropriate to the memory limitations of the device.

These recommendations relate to the issues of content quantity and file size.

For content quantity, the issue is how much content to put in one topic versus breaking that content into several smaller topics. This is partly related to topic-based authoring and partly just an arbitrary issue of file size.

“Topic-based authoring” says we create content in small, fairly self-contained units – topics. “Fairly self-contained” means that each topic tries to answer one question – “what is”, “how do I”, etc – with related but separate information in separate but linked topics. For example, consider changing a tire on a car.

One topic might cover the steps for changing the tire, and link to another topic that covers safe jacking practices, another that explains where to find the jack and lug wrench, etc. This structure, plus tight writing in general, keeps each topic as small as possible. But is isn’t perfect; different topics may follow the same “one-question” model but still have very different lengths. For example, a command reference section in a programming manual might cover command A in a quarter of a page but need three pages to cover command B.

On large-screen devices, this may be a design problem but isn’t a technical problem. The browser or help engine will display topics that are as long as you need, even if you don’t like the excessive scrolling. If the scrolling is too bad, you can add an “in-topic” links list at the top of the topic to let users jump directly to a desired section in the topic.

In mobile, however, length raises many problems. Reading scrolling material is hard on large screens but worse on small ones because you see less material per screen. Zoom the mobile screen to make the text legible and you’ll see still less plus add horizontal scrolling to the vertical scrolling. The “in-topic” link list idea just takes up valuable screen space. And, a long topic that works on a large-screen device may exceed a mobile device’s file size limits and get truncated on the display.

What to do about these problems?

• If you create content now for large-screen devices but see mobile being added to the mix, you first need to know the file size limits of the mobile devices you’ll be supporting.

• Based on those limits, you need to review your topic lengths to see if any are too long and, if they are, break them into separate smaller topics and/or edit them.

• Also, if you don’t use any particular methodology for writing content now, or if you’re coming to mobile from a hard-copy output environment, look at topic-based and structured authoring to see whether they’ll help you a) define consistent information types, b) create topic templates that you can use to apply a consistent structure to the material, and c) break the material into smaller topics based on the information type analysis. (There’s a degree of self-interest in this paragraph since I teach topic-based and structured authoring, but that doesn’t reduce its utility.)

• Finally, if you haven’t reviewed your content for a while, this is the time to see if your editorial standards have slipped a bit and let fat creep into the writing.

In summary, topic length issues depend on two things, much as in the previous post:

• Knowledge of technical issues – what devices, microbrowsers, standards, etc. will you use and what file size/topic length limits they impose?

• Knowledge of strategic content issues – what outputs do you need, what content applies to those outputs, and how to define and control that content?

Again, needs assessment and configuration analysis before moving to mobile – the same things we’ve always had to do but taken in some new and sometimes extreme directions.

More to come…

Thursday, October 21, 2010

W3C Mobile Web Best Practices and HAT-Based Mobile – Part 5

Next, a recommendation that applies to a common feature in online help and doc, popups.

13. [POP UPS] – Do not cause pop-ups or other windows to appear and do not change the current window without informing the user.

The first part, about pop-ups or other windows, is what most applies to tech comm. The W3C states “Many mobile devices cannot support more than one window… attempting to open one will have unpredictable results.”

It’s safe to assume that, for now, the mobile devices we use can’t show popups. Trying to open a popup may produce an error message, as in RoboHelp’s ePub, get converted to a jump link, as in Flare’s WebHelp Mobile, or do something else unpredictable. But popups are common in online documents and online help. What do we do?

The answer is to back up to the top level of abstraction and define two things, our project's outputs and their priority. We’ll then define a feature set based on the priorities. For example, do we want online help and hard-copy, with online having top priority? If so, we’ll define a feature set that’s best for online but may not convert to and work as well in hard-copy. If our priorities change, the feature set may have to change to match. (The authoring tool may even have to change.) The crucial thing is to consider how the feature set will work across all the desired outputs, not just focus on the top priority output.

Consider this approach in regard to popups …

• If our outputs are online and mobile and online has top priority, we pick features that are most effective for online and conditionalize them out for mobile. For example, we create popups and use them in the online output but conditionalize them out for the mobile output.

• But if our outputs are online and mobile and mobile has top priority, we may not use features that don’t work in mobile without considering that they do work in online. Ensuring that we consider all the outputs might instead suggest that we create and use popups but still conditionalize them out for the mobile output.

In summary, the question of whether to use popups depends on two things:

• Knowledge of strategic and business issues – what outputs you need, with what priority, and on what devices used in your market.

• Knowledge of technical issues – what microbrowsers or standards are used on your output devices, what help authoring tool features they support, and how those features convert.

It comes down to doing a needs assessment and configuration analysis before starting the project – the same requirements that we’ve always had to deal with but simply taken in a few new directions.

More to come…

Wednesday, October 13, 2010

W3C Mobile Web Best Practices and HAT-Based Mobile – Part 4

Next are three related recommendations that have to do with creating content – what we used to call writing…

17. [SUITABLE] – Ensure that content is suitable for use in a mobile environment.

The W3C says “Users in a mobile context are often looking for specific… information, rather than browsing.” This is also true of online material from tech comm., especially online help.

For example, people don’t browse online help; they read it for specific information they need to do some task. But this may not be true of other types of online material. For example, you may create online procedure manuals for use in the field. In such manuals, users might browse the content or read larger chunks than they would in online help because there’s more to know or learn about the subject.

So this recommendation requires analyzing our content in order to determine:

• What parts don’t apply to the mobile output’s functional environment. You’d remove those parts by conditionalizing them out for the mobile output – e.g. single sourcing. For example, information about configuring an application for a printer might be useful in large-screen online format but irrelevant for mobile.

• What parts don’t apply to or aren't crucial for the mobile output’s usage environment – “need-to-know” versus “nice-to-know”. You’d remove the latter from the mobile output by using conditional build tags. For example, you might create an online shopping guide to single malt scotch that showed each brand’s label in the large-screen version. However, while showing the label might still be nice in the mobile output, there isn’t enough room on the screen so you’d decide to hide it and use the space for more appropriate content.

18. [CLARITY] – Use clear and simple language.

This should be a given in tech comm.; write in clear and simple language... The reality is that we often don’t. The passive voice is used by us rather than active voice. We address “the user” rather than “you” and get tied up in gender-neutral writing like “The user... They…” and “he/she…”

If you know your content will be single sourced to mobile devices, change your writing style now to short and simple. If you have a lot of legacy content, this may require more work than you can afford and you may decide to leave the legacy content as is. However, it may be worth a quick look at that legacy content to see if there are any simple writing fixes that offer a quick payoff for a low investment. For example, can you replace the phrase “… enables you to…” with “… lets you…”, as in “This feature enables you to…” with “This feature lets you…” This sounds trivial, eliminating six characters out of the twenty-seven original ones, but consider that that’s a 22% reduction in that one phrase.

I’ll add that if you know you’re heading toward mobile output, consider getting an editor to do traditional tasks like copy-editing in order to shorten and simplify your content for mobile in particular, and any writing in general. If you’re an editor, doing a before-and-after edit might be a way to sell your services to companies that are moving toward mobile output and have large amounts of textual content.

19. [LIMITED] – Limit content to what the user has requested.

This recommendation suggests that content may have to change dynamically in response to user requests. This suggests the presence of a database on the server that reconfigures the content in real-time. That capability is starting to become available for tech comm., currently in AuthorIT’s Aspect product (http://www.author-it.com/index.php?page=aspect), but is still an enterprise-level product and thus not cheap.

To a degree, however, we can limit the content to what user request by making the most rigorous possible use of topic-based authoring – writing the content in small chunks and giving those chunks the clearest possible titles, index entries, search synonyms, and other retrieval mechanisms that our authoring tools support.

In summary, if you’ve written the content tightly, used topic-based authoring rigorously, and identified what content applies to what functional and usage environments, then you should be on track to support single sourcing to mobile. And the points in the previous sentence are simply good writing anyway, mobile or not.

More to come…

Tuesday, October 5, 2010

W3C Mobile Web Best Practices and HAT-Based Mobile – Part 3

The next recommendation, again in the order in which I’m getting to them…

6. [NAVBAR] – Provide only minimal navigation at the top of the page.

For years, help authors have used the “tri-pane” window created by Microsoft for HTML Help in 1997. This model, adapted for the web-oriented WebHelp model created by eHelp, original vendor of RoboHelp, in 1998, put the major navigation controls – TOC, index, and search – in a vertical pane at the left side of the help window. It added a horizontal toolbar for the nav function labels and custom functions, as shown below:

The problem with this model on mobile devices is that the tiny window can only show a tiny part of the screen; it can take many (irritating) horizontal and vertical scrolls to get past the toolbar and navigation controls to the actual content. What to do about this?

The W3C suggests “provide basic navigation… on the top of the page… secondary navigational element[s] may be placed at the bottom of the page if really needed… users should be able to see page content once the page has loaded without scrolling.”

This is a perfectly sound recommendation. However, when it comes to HAT-based online documentation or help created using tools like Flare or RoboHelp, the navigation options can use a lot of screen space even without the horizontal toolbar.

A solution implemented by Flare in WebHelp Mobile and RoboHelp in ePub is to revert to the old (pre-HTML) Windows Help model. This output had the content and navigation in separate, single-pane windows, only one of which could display at a time.

For example, start a WebHelp Mobile online document and the navigation pane displays. Select a topic, from the TOC for example, and the content pane replaces the navigation pane. ePub takes a similar approach on the devices I’ve seen. (This may be modifiable in the interface. It’s on my list of things to check.)

Some observations about this model:

• Users can only see content or navigation – not both simultaneously, unlike the tri-pane model that they may have become accustomed to over the years. This may take some getting used to. Not much, but people rarely expect “books” to change their format.

• Flare’s mobile output skin is more limited than its regular skins because there’s less screen space. This is important if you created custom navigation or other buttons for your regular WebHelp output only to find that there isn’t room for them in mobile. Ditto for a RoboHelp project that you output to ePub. (And ePub’s navigational interface is largely fixed.)

• Finally, an example of why you can’t just test your mobile output on emulators. If you output a RoboHelp project to ePub and test it on the ADE (Adobe Digital Editions) reader, you’ll find that ADE uses a left-right split screen model that shows the navigation features on the left and the content on the right. Open the same eBook on a physical device, however, and you’re back to single-pane mode. This may be modifiable through the ePub code, but the need for any custom coding makes the HAT-based output less convenient.

In summary, if you’ve stuck to the basic navigation offered by your HAT, you should be okay when you convert to mobile. But if you’ve created custom features on the navigation pane or toolbar, you may have to re-think your design when you go out to mobile.

More to come…

Thursday, September 30, 2010

W3C Mobile Web Best Practices and HAT-Based Mobile – Part 2

Continuing the previous post, here’s the next recommendation…

22. [SCROLLING] – Limit scrolling to one direction, unless secondary scrolling cannot be avoided.

The screens on which we typically display help are large enough to fit almost any graphic or table without forcing users to scroll horizontally as well as vertically. When horizontal (“secondary”) scrolling is needed, it’s rare enough that we can excuse it as an unfortunate exception from our design.

It’s not that simple when we single-source help projects to mobile devices. Mobile device screens are so small that almost any graphic or table might need horizontal scrolling. This is okay technically, but it reduces usability. How to deal with this? Four ideas:

1. Accept it. That wide graphic or table may be necessary to convey the information.

2. Modify it. For a graphic, we may be able to crop out and display small sections of the graphic rather than the whole thing. For a table, we might be able to restructure it in order to narrow it. But modification is iffy, since it runs the risk of losing or confusing the original meaning of the material.

3. Conditionalize it. You may decide that you can live without the graphic or table in mobile output, or that you have to live without it because you can’t modify it to fit on a mobile device screen. You might define a condition called “mobile”, apply it to the graphic or table, and exclude anything conditionalized as “mobile” when you generate the output.

4. Define its size in relative instead of absolute units. Replace points, pixels, or other absolute size units with relative units like % or ems, among others. For example, you might change a graphic’s width from 180 pixels, which may add horizontal scrolling, to 100%. This says that the graphic’s width is 100% of the available space in the window, no matter what the device, and leaves it up to the browser to figure out exactly what that is, including on a mobile device. This approach works but has several quirks.

• It’s easy to shrink a graphic to fit into the space of a mobile device screen but the result may be too small to read. In that case, you might have to conditionalize it out after all. Ditto for tables.

• The graphic may show quirky behavior when inserted into a table and output to ePub format. This happened with an output from a RoboHelp project. I don’t know whether the problem was in the ePub standard itself, the RoboHelp converter, or my project specifically. To be investigated…

More to come…

Monday, September 27, 2010

W3C Mobile Web Best Practices and HAT-Based Mobile

In the ‘90s and early ‘00s, products like Newton and standards like WAP and CE tried to get mobile computing into the mass market. They all failed due to shortcomings in technology, usability, and interoperability. Never mind largely silly content…

In the early ‘00s, to help give mobile computing another crack at the mass market, the W3C (WorldWide Web Consortium) began an effort called the MWI (Mobile Web Initiative) in order to set technical and best practice standards.

I've followed this effort closely for years – I’ve been working with, training on, and looking for markets for mobile since ’98 (thanks to Joe Welinske, who introduced me to Windows CE in '97) and was the STC’s (Society for Technical Communication) representative to the W3C from ’02 to ’05 so I had a dual interest. But the mobile mass market never went anywhere until Apple brought out the iPhone and sent the market skyrocketing.

A side effect of mobile’s skyrocketing in the mass market has been a slow but steady rise in interest in using mobile for tech comm. Until recently, creating content for mobile, in the form of apps, was so different from “true” tech comm and online help that there was little or no overlap. Tech writers had to do “apps” to get into the mobile space.

That’s changed in the last year, as two well-known help authoring tools (HATs), MadCap Flare and Adobe RoboHelp, added support for mobile output. (There may be others too; I happen to support Flare and RoboHelp so they’re the ones I’ll focus on. But what follows applies to any HAT that offers mobile as an output.)

As part of the MWI, W3C created several standards including Mobile Web Best Practices Basic Guidelines, a Recommendation as of 29 July 2008. (www.w3.ord/TR/mobile-bp/) It offers 60 recommendations for creating, coding, and structuring of content.

It was NOT written with HAT- based mobile in mind, but many of the recommendations do in fact apply to HAT-based mobile, either directly or with some tweaking. Because of that, the rest of this post and a series to follow will examine these recommendations from the point of view of creating HAT-based mobile output. I’ll discuss the recommendations as I get to them, which means I won’t address them in the same order as they appear in the W3C document. But I will use the recommendation numbers for reference. Starting with…

4. [TESTING] – Carry out testing on actual devices as well as emulators.

Testing on emulators is convenient. Passing output to the emulator is built into the HAT’s interface, so it’s a matter of a few mouse clicks. Flare has its WebHelp Mobile emulator, and RoboHelp uses the Adobe Digital Editions (ADE) application as its ePub emulator. Both work fine, but both have the same issues as every other emulator I’ve seen. (In other words, this is not a criticism of either vendor’s emulator but an assessment of emulators in general.)

• They can’t simulate network traffic loads because they’re not on a network, so there’s none of the delays that might occur in the real world.

• They’re driven by the full processing power of the PC on which they’re being run, rather than by the more limited processor and memory of the real mobile device, so they run more quickly and smoothly.

• They may not offer the unique behaviors of the real devices, such as the touch-screen interface, so the user experience isn’t faithful to reality.

• You may also get some odd behaviors in different emulators, even those for the same standard. For example, if you output a RoboHelp project with multiple topics to ePub and display it in ADE, the result displays all the topics in ADE as one long scrolling file – basically a “book”. Display the same output in Firefox using its epub plug-in, however, and each topic from the project displays as a separate web page. This means that you’re going to get different behaviors for things like scrolling – through the whole book versus one topic at a time, for example.

So you’re ultimately going to have to buy examples of each device on which your mobile content is supposed to run and test accordingly. That’s nothing new for Engineering, but it may be a new experience for a doc group. The doc group would either have to set up its own publishing, testing, and QA processes and lab or work very closely with Engineering in a new and unusual way.

More to come…

Thursday, September 16, 2010

A Business Side to Tech Comm “Initiatives”

Changing how a doc group works – new tools, new output formats, a new development methodology, etc. – has long-term strategic effects on the group and its relationship with groups like Engineering or Sales. These effects mean that such changes need to be “sold” – what’s their strategic and financial effect on the overall business? Will they lead to lower costs, higher sales or market share, more efficiency, better regulatory compliance, or some other benefit?

There’s so much information about this business aspect of proposal writing that it can be hard to know where to start. One good starting point that I recently found is a book called Maximizing Project Value by Jeff Berman, from AMACOM (www.amacombooks.org).

The book describes a project proposal methodology called Speed2Value, but the write-up is generically applicable to any project. It focuses on the strategic rather than the tactical, stressing a proposed project’s effect on the company rather than just looking at whether the project was finished on time and on budget.

The book also provides an overview of cost-justification methodologies like ROI (Return on Investment), NPV (Net Present Value), Payback Period, and IRR (Internal Rate of Return). It doesn’t go into a lot of technical detail, just enough to provide a starting point for further research or actually writing a proposal. The book is presented in lay terms, is clearly written, and is a quick read (I read it on a plane between Boston and Phoenix). It’s worth buying.

Why Use Twitter For Tech Comm?

Excellent blog post on why to use Twitter for tech comm. See http://tinyurl.com/yg3f76p

Thanks to Cheryl Landes for this recommendation.

Tuesday, July 27, 2010

The Future Arrives Earlier Than Expected

One sure-fire aspect of writing trends articles is knowing that I’m going to be wrong about something. What’s entertaining is seeing just how quickly that can happen...

In December, 2009, I wrote an article about trends for STC’s Intercom magazine in which I predicted, among other things, “dynamically reconfigurable outputs,” which I described as follows:

“One problem with documentation is our inability to create one output to handle everyone’s needs. We can use conditions to create multiple outputs from one project, but this creates multiple outputs to which we then have to steer readers. It works, but the development is inefficient and can be confusing. Instead, what we need is the ability to create one output that dynamically reconfigures itself based on readers’ login permissions, requests (“Only show me material related to Idaho.”), or external stimuli (like an aircraft maintenance manual whose content varies depending on whether the outside temperature is above or below freezing). This technology will simplify distribution of information by reducing the number of outputs. It would also let us create output that responds to readers’ needs rather to our estimate of their needs.

Assessment – This technology is under development now, but every effort that I know of is still proprietary. I expect it to appear in mainstream tools in the next few years…”

Four months later, at the WritersUA conference in Seattle in March, 2010, I mentioned this idea to a representative of AuthorIT. After he stopped laughing, he said AuthorIT had come up with just such a product in mid-2009 but hadn’t gotten around to serious marketing until WritersUA. So I basically had the prediction right but the timeline badly wrong.

The product is Dynamic Assistance Platform, or DAP, one of whose components is called Aspect. As the AuthorIT site describes it “…The content is personalized for the person viewing it by matching information in the content with their login profile. This means that when a user views content, it is content that has been filtered for their profile…”

From what I got at WritersUA, Aspect may not be for everyone – as an enterprise-level product, its cost may be too high for small doc groups or applications. But it is the first commercial implementation I’ve run across of what sounds like a really useful idea. Even if you use another authoring tool, it’s worth reading about. See http://www.author-it.com/index.php?page=aspect

Monday, July 5, 2010

Blog About Mobile eLearning

Interesting blog re mobile, specifically SMS-based, eLearning at http://tinyurl.com/27ag2my.

I agree with the third commenter, Sue Cloud, who argues that the blog is talking about bits of communication rather than true learning per se, but I suppose this is a matter of definition - e.g. if you consider the Tip of the Day that appears when you start an application to be "learning," then this can indeed be considered "learning."

Thanks to Cheryl Landes for this tip.

Friday, June 18, 2010

Questions from Captivate Course in Orlando

Chris and Anthony,

To delete misspelled terms that you accidentally add to the dictionary - This is mentioned in the help. Terms that you add to the dictionary during a spell-check go into your personal dictionary, userdic.tlx, which you should find at \\Documents and Settings\\Local Settings\Application Data\Adobe\Adobe Captivate\Spelling.

To delete the Adobe logo from the movie playbar - You'll have to use a different skin. To do so, select Project > Skin Editor and select any other skin listed in the Skin field in the upper left corner of the dialog box.


Sunday, June 13, 2010

Workshop – Creating Mobile Device Output Using Flare

Need to create output to run on mobile devices from a Flare project but not sure how? You could create an app, but the process may be unfamiliar to your developers and call for new tools. Or you could use Flare itself to create the mobile output, in the form of a "site" that should run on most mobile devices that have a microbrowser.

Generating mobile output from a Flare project is simple mechanically. Where things can get tricky is in the design and control of the content – deciding what content to show or not show in mobile form and controlling that, controlling formatting by making full use of possibly unfamiliar CSS features like mediums and relative sizes, and more.

This half-day, hands-on, web-based class is aimed at Flare 6 users who need to quickly get up to speed on converting existing projects to Flare WebHelp Mobile output. Prior experience on at least one Flare project is necessary.

- Date - Monday, July 12, 9 AM to 12:30 PM ET.

- Cost - US$150 per person, includes workbook and working files.

- Location - Remote, via GoToMeeting.

- Outline – see www.hyperword.com/FlareMobile.htm.

Contact Neil Perlin at nperlin@nperlin.cnc.net to register or for information about payment.

Tuesday, June 8, 2010

Creating Mobile Output with Flare

New half-day, hands-on workshop on how to convert online help or doc projects created using Flare to mobile format. Covers the conceptual background, conditions, CSS mediums and relative size settings, the mobile skin, and testing.

See http://www.hyperword.com/FlareMobile.htm

First of a series of workshops on mobile and tech comm.

Tuesday, June 1, 2010

Adobe RoboHelp’s Mobile Output

Continuing my look at help authoring tool-based mobile output, we turn to RoboHelp 8.

RoboHelp mobile output uses the International Digital Publishing Forum (www.idpf.org) ePub standard. This means the output can run on any device that supports ePub, like the Barnes & Noble Nook, Android devices with ePub readers, Kindles (with some extra work that doesn’t involve RoboHelp – see http://kindleworld.blogspot.com/2009/08/ million-free-google-books-in-epub-for.html) and others.

RoboHelp creates mobile output using a script that you import into RoboHelp itself. (This is similar to how Adobe added AIR support to RoboHelp – using a plug-in in v.7 before adding it to the interface in v.8. If the mobile market takes off, I’d expect to see Adobe follow the same path and build the script into the interface in v.9.)

What follows is an overview of what’s involved mechanically and design-wise in converting a fairly standard project to mobile format. The project is a proof-of-concept I created for a Boston-based maritime historical to which I belonged from 1990 to 2003. Members of the group built museum-class ship models, and my idea was to create an online “book” about the models and have it sold in the museum store as a fund raiser for the group.

Here’s the main screen and default topic:

And here’s a fairly typical topic screen.

The project had a TOC, index, header and footer in one topic, breadcrumb trail, table and graphics, internal links, an external link, popups, and an audio file. My question was how well the project would convert to mobile with no effort on my part.

The first step is to download the ePub generator script and a file archiver, both free. (See Ankur Jain’s blog at http://blogs.adobe.com/techcomm for instructions.) A few caveats – you’ll have to change the name of the script file to ePubGenerator.jsx and modify the script – a minor step into code – to specify where you put the file archiver on your PC. You can then import the script into RoboHelp using the Script Explorer. Finally, you have to change the XML handler using RoboHelp’s XML support feature.

You can then open the project to be converted to mobile format and run the script. After you specify the output folder, RoboHelp will create the ePub output. Here’s the result in Adobe’s ePub viewer – Digital Editions. First the main screen and default topic:

And the topic.

The result? Mechanically, pretty good. Without making any changes to the initial project, here’s what I got…

• Text converted correctly, as expected since ePub offers “reflow” of text. The text also resized correctly when I used the resizing options on the viewer.

• The TOC came across fine.

• Internal jump links worked fine. External jumps worked too, but opened the target pages in a new browser window. This is okay if your users will read the book in a full browser, like Firefox with the ePub reader add-on, but not if users will read it in a “true” reader. Popups did not work, which I assume is because ePub doesn’t support them.

• Graphics seemed to come across fine.

The problems I found seemed to have more to do with apparent incompatibilities between help project features and the ePub standard, and design.

• The index didn’t convert. I’m not sure if this is because ePub doesn’t offer one or because of something that simply hasn’t made it into the conversion script yet.

• The search tab didn’t convert. It was replaced by the ePub viewer’s search tool, as can be seen, with some difficulty in the images above, at the end of the toolbar.

• One oddity – the project apparently converted to one text file when viewed in the Digital Editions viewer but individual topics when viewed in Firefox. I assume there’s a reason for this that I simply haven’t found yet.

• Projects meant to be single sourced to ePub, in addition to any other outputs, need greater and more rigorous use of CSS. Basically, avoid local formatting – good advice under any circumstances.

• Adobe recommends setting sizes as % rather than the usual points. You’ll have to do this for everything, not just text. Also, don’t use hard returns for paragraph or table row separators because these double when rendered in ePub. (Compare the paragraph spacing in the pre- and post-conversion versions of the default topic, and the spacing of the table rows in the pre-and post-conversion versions of the ship topic.) Instead, specify the spacing as part of the style for the items in question.

• There are also some formatting requirements described in Ankur’s April 23 post.

Finally, as you’d expect when converting content from big-screen to little screens, you’ll have to decide what content is “need to know” versus “nice to know,” such as graphics, and be prepared to conditionalize out the latter. You can fit many graphics in the mobile output by making their sizes relative, with the % unit of size, but a graphic may become small enough to be illegible. Think of this as single sourcing taken to an extreme level.

The biggest benefit of this support for mobile output is the fact that it makes it easy to try mobile without buying and learning new software. And, if you don’t like the result or it’s not what you needed, just delete the output, delete the script (or just ignore it), and go back to your regular output.

And, again, it’s challenging and fun to figure out how to output to mobile…

Friday, May 28, 2010

Upcoming mlearning (Mobile Learning) Conference

mLearnCon, a mlearning (mobile learning) conference in San Diego June 15-17:


Thanks to Cheryl Landes

Thursday, May 27, 2010

Interesting Review of the iPad in Time Magazine

Here's the link - www.time.com/time/business/article/0,8599,1976932,00.html

Thanks to Deb Sauer, Deborah Sauer Consulting

Wednesday, May 26, 2010

TE SIG Mobile Content Session - Demos via GoToMeeting

As I said at the TE SIG meeting last night after my laptop wouldn't sync up to the projector, I'm going to show the live demos of various authoring tools and emulators via my GoToMeeting account instead.

In order to try to take people's schedules into account, I'm going to run the demo twice in 45 minutes sessions on the following days:

Wednesday, June 2, from 9 to 9:45.
Friday, June 4, from 1 to 1:45.

If you can make either of these sessions, email me at nperlin@nperlin.cnc.net and I'll send you the meeting ID. If you can't make either of these sessions, let me know at the same email and we'll try to work something out.

Friday, May 21, 2010

MadCap Flare Goes Mobile

In a recent post, I discussed how RoboHelp 8 has added support for mobile output. In this post, I’ll look at Flare 6 and its support for mobile output. Again, some background about the mobile space…

Mobile debuted in the early ‘90s with Apple’s Newton. Newton was revolutionary, but its problems turned it into a footnote in computer history. Windows CE Help and Wireless Markup Language followed several years later, but failed in the mass market for, in my opinion, three reasons. One was an unattractive output, shown below in a real screen from a presentation that I gave in 1998:

That problem has been corrected, as evidenced by the examples below – iPhone apps for star charting and birding:

Another problem was that vendors didn’t know what content to offer so they offered anything, much of it “fluffy” novelties whose charm wore off quickly and that lacked staying power for the mass market. Many apps today share that problem, but there are a lot more apps so there’s a better chance of finding something good amid the fluff.

The third problem in ‘98 was a rough authoring environment, often requiring hand coding. Authoring can still be difficult, but there’s a decade’s worth of improvement in the tools.

So, in general, mobile has become easier to create and more attractive to use.

For today’s technical communicators, there’s a new problem however. Do we create apps, or help or doc to be read on mobile devices? App development is new for many technical communicators and can take them into unfamiliarly complex authoring issues. But the help authoring tools, or HATs, offer another approach – letting us put online content into a format that works on mobile devices and either stands on its own, like an online procedure manual for use in the field, or help for a real mobile app. (If you think today’s mobile apps are so simple as to need little or no help, you’re right. But as mobile device power keeps increasing, I expect increasingly powerful apps to appear that will need help.)

Flare offered mobile output as an option in the interface when it released v. 6 in March. In this post, I’ll give an overview of the feature set and results. Another article will appear in a forthcoming issue of the Communicator, the journal of the ISTC (Institute of Scientific and Technical Communications) at www.istc.org.uk.

Flare 6 supports mobile output through its WebHelp Mobile output target. The target is integrated into the Flare interface, so using it mechanically simply involves creating the target, selecting WebHelp Mobile as the output type, setting or selecting various options, and generating the output. Most of the options are familiar ones in Flare, such as skins, TOCs, CSS mediums, and so on.

How well does it work? Here’s my test project, output as standard WebHelp:

And here’s the same project output in mobile form:

What’s striking about this test is that I made no changes to the project except for the skin settings; Flare just gave me the material in a different format. This has strategic effects for development. If you’ve wondered what your online help or doc would look like in mobile form, you no longer have to buy and learn new tools. Instead, just select mobile as the target. And if mobile proves not to be what you need, just delete the mobile target and try something else. In other words, there’s no risk to trying mobile.

More specifically:

• WebHelp Mobile produces a “mobile site” rather than a “mobile app” so it’s not tied to a specific device. It’s simply a web site accessible from any device with a microbrowser.

• The code is “pared-down” XHTML, so it’s open-source.

• WebHelp Mobile automatically adjusts to a microbrowser’s features. For example – no JavaScript support means no search capability or dynamic text features. This automatic adaption to the microbrowser’s capabilities simplifies project planning, design, and management.

• Flare has pre-defined mobile skins, so skin definition is just point-and-click.

• There’s a generic emulator to preview WebHelp Mobile, shown below:

• All standard navigation options are available on the home page, as shown below.

Mechanically, outputting a project to mobile is a snap. The problems arise in design. This isn’t a problem in Flare but rather in the need to fit output designed for large-screens onto a screen the size of a sticky note. My test project has a fairly typical feature set. Here’s a summary of what happened on conversion…

• Text and variables (which are text) converted smoothly because they reflow to fit the screen sizes.

• Objects that are too big converted but added horizontal and/or vertical scrolling. (Scrolling reduces usability but isn’t necessarily evil, but avoid combining both types of scrolling at the same time if you can.) You can expect this problem with tables, graphics, drop-downs and togglers that contain tables or graphics, master pages, wide head styles, and SWFs. Snippets and project import link items can also be troublesome because they may have the same problems but you won’t “see” it as you insert them – basically “out of sight, out of mind.”

• Popup links converted to jumps. Some microbrowsers don’t display popups, so making the popups work as jumps supports the lowest common denominator microbrowser.

• The only other problems I’ve found or heard about so far are due to the limitations of the display devices themselves. For example, WebHelp Mobile should be able to use a regular project’s header and alias files to create context-sensitive help for mobile apps, but the device must support multitasking or else opening the help closes the app.

• Finally, there’s the design problem of deciding what information to omit from the mobile output.

Except for the last point, you can deal with most of the other problems by making fuller use of Flare features. For example, style properties should be relative rather than absolute – % or ems for text size instead of points for example. This isn’t unusual for text, but what may be unusual is the need to do so for tables and images. (You’ll want to create a CSS medium for the mobile output.) For example, here are two versions of the same page, one with the graphic displaying at its default size and the other with the height and width set to 50%. Note how the second one eliminated the horizontal scroll bar.

This isn’t that difficult, but it will require you to look more closely at your styles and properties and maybe try some features of the Stylesheet Editor that you’ve ignored until now. You’ll also make greater use of conditionality, and perhaps variables in order to use full names in the regular output but abbreviations in mobile. You may also have to re-evaluate your content to determine what’s really needed and what’s there because it’s cool and you had the screen space to indulge yourself. And so on…

If you’re a Flare shop and considering mobile output, you’ll find that the mobile target will push you into new areas of information design in general and Flare’s feature set in particular. And it’s fun…

Tuesday, May 18, 2010

Open Questions From Single Sourcing Class in Canada on May 13

Here are the answers to the open questions from the Single Sourcing class in Scarborough last Thursday, May 13

In what format does Flare output PDF – Adobe.

Do mathematical expressions convert correctly – Depends on the version of Acrobat you have. Check your version's specs.

Do custom templates have to be in the My Documents/My Templates folder – Yes in Flare through v.5. V.6 now lets you put templates wherever you want by using the Template Manager dialog box, available by clicking the Manage Templates icon on most Add New… dialog boxes.

Can you physically exclude topic files (.htm) from the output folder – Conditionalize the topic at the topic level, not at the content level in the topic, and then exclude the condition from the build to physically remove the topic’s .htm file from the output folder. This did NOT work the first time I tried it, but it did when I tried it twice more so I assume I missed a setting the first time.

Can you have topics’ content output to print without listing the topic in the TOC in Flare – No. Flare uses the TOC to select and sequence the topics to output to print, so removing a topic from the TOC in Flare removes that topic’s content from the output. You can work around this by leaving the topic in the Flare TOC for output to Word, then removing the topic’s content from the TOC in Word.

Thanks to Alvaro in tech support for several of these answers...

Wednesday, May 12, 2010

May 25th Boston STC SIG Meeting on Mobility and Tech Comm

This is a reminder about the Technical Editing SIG presentation that I’m doing for the Boston chapter of the STC on May 25 in Natick, MA. (See the chapter site for the address, times, and directions - www.stcboston.org/sigs/te_sig_may2510.shtml.)

I’ll start by discussing the rationale for mobile content, and for tech comm to be creating that content as part of our regular role. Then the history of mobile, briefly – one slide, followed by three reasons why mobile information may succeed this time.

I’ll then cover three target options, two architecture options, and two dev options, with the dev options focusing on using HATs like Flare or RoboHelp to create mobile content vs. using dedicated mobile web authoring tools. Finally, I’ll look at what standard online content design elements work or don't work in the HAT-created content and how we’ll have to change some ways in which we work in order to fix those things and add mobile to our repertoire.

I’ll also demonstrate a number of readers and emulators including, at the moment but not officially, MadCap’s WebHelp Mobile viewer with content from Flare 6, Adobe’s Digital Editions ePub emulator with content from RoboHelp 8, an Android emulator, a quasi iPhone emulator, Firefox in small-screen rendering mode, and whatever other tools I can set up between now and the 25th.

And if you're interested but can’t make it, email me and I’ll send you the slides.

This stuff is fascinating...

Monday, May 10, 2010

The Return of Location-Based eCommerce

One benefit of longetivity in any field is the ability to see cycles. The latest cycle I’ve seen is the return of location-based eCommerce – an interesting idea (just as it was ten years ago).

Consider an article entitled Social Media’s New Mantra: Location, Location, Location in the May 10-16, 2010 edition of Bloomberg Business Week. The article discusses the promise of social media-based, location-based ecommerce. It focuses on several companies that are moving into this space or that already have a presence, ranging from startups to existing companies. The article suggests the example of an iPhone app that checks your friends’ calendars to see if they’re free for the evening, suggests a restaurant that everyone’s wanted to try, notes table availability, and notes where your friends are to make it easy to hook up. Cool…

Now consider this description...

… there’s a specific type of location-based application that’s likely to affect technical communicators – lCommerce (“l” for Location), or mCommerce (“m” for Mobile)… these applications will determine your location and try to sell you things based on that location. For example…

• The florist’s site beeps you when you’re within a mile of the store to remind you that tomorrow is Mother’s Day.

• The car wash beeps you as you drive by on the day after a blizzard to remind you that road salt is bad for your car’s chassis – why not come in right now?

• You’re looking for a Cajun restaurant in an unfamiliar city, find one on an online restaurant list, select it, and have a web site detect your location and continuously provide directions to the restaurant

More ambitious applications could bring people together by detecting their relative locations. For example, a Starbucks’ site might call as you drive past and tell you that your friend Bob is inside and that you’ll get a dollar off a latte if you drop in now. Or that florist’s site might beep to tell you that tomorrow is Mother’s Day but warn you that your mother is in the store right now.

This latter description is from a column that I wrote for Intercom, the magazine of the Society for Technical Communication, in February 2001. I ended that column with this prediction as to how location-based apps might affect technical communicators.

… should see two types of work coming out of the location-based applications. First, there’s likely to be an increase in site development work as local businesses decide to create web sites. Second, given the high potential for irritation…, we may find work creating filters to block calls from the same sites that we created. If all this sounds unlikely, remember that it isn’t too long ago that the idea of technical writers creating web sites was ridiculous. Location-based applications will be an interesting addition to our repertoires.

I’d have to say that I got this prediction wrong. (There may be technical communicators out there who do this type of work, but I’ve never met one.) However, as society becomes increasingly mobile, the idea is still sound and the technology is a lot better than it was in 2001. I have no idea what might come of this technology, but it is worth watching.

Thursday, May 6, 2010

RoboHelp Goes Mobile

Help authoring tools, or HATs, have been around for a long time. RoboHelp, the second oldest HAT, appeared in 1991/92 – impressive longetivity in a technical field.

HATs stay alive (business issues aside) by constant adaptation in the face of technical changes. For example, HATs in general could have disappeared in 1997 when Microsoft introduced HTML Help, since we could now create online help with web authoring tools like Dreamweaver. Many of the original HATs did in fact fail to make the shift to HTML and disappeared. But the larger, better funded ones like RoboHelp and Doc-To-Help did make the shift and are with us today.

That large-scale adaptation has continued since 1997, with the incorporation of support for PDF, XML, DITA, and now, mobile output, the focus of this post.

The mobile space has been chaotic since the late 1990s. Technologies like Windows CE Help and Wireless Markup Language looked good but failed to penetrate the mass market for several reasons, a major one being the fact that mobile output looked like this in 1998 (a screen from a Wireless Markup Language presentation that I gave back then):

This was a simple mobile app designed to teach the coding, but full-scale apps weren’t all that much more exciting. The screens were grey and bland compared to what we expect today, which looks more like this…

So mobile content and mobile apps are more inviting than they were a decade ago. And the explosive growth of the iPhone, Android, RIM, and other mobile devices has given mobile a degree of market credibility that it hasn’t had before. So it makes sense to start looking at mobile. And yet…

Many companies are reluctant to try mobile for three reasons:

• There may not appear to be any environments in which their apps can be used in a mobile mode. But some uses just may not be immediately obvious. For example, accounting apps might be used in the field for inventory control and need mobile-style online help. Or reference guides containing settings for pollution sensors in a food processing plant might be more usable on a mobile device when the sensors are mounted up near the ceilings.

• Companies may be looking at the market for mobile apps or help or “content” and find the choice between the various platforms to be too confusing or chaotic to be able to pick one.

• Companies may have tried mobile before and been disappointed by the feature set or burned by the reception in the market.

In each of these cases, companies will be rationally reluctant to invest in new tools. But if your company uses certain HATs, and I’ll focus on RoboHelp here, there is a way to test the mobile waters almost effortlessly.

On April 23, Adobe released a RoboHelp 8 script that converts RoboHelp projects to the ePub format. ePub is a standard from the IDPF (International Digital Publishing Forum) for “reflowable” text, which essentially means that content can change its width to take into account the width of the screen on which it’s being displayed. You can find the instructions for downloading and installing the script, along with suggested best practices for coding content, on the blog of Ankur Jain, RoboHelp Product Manager, at Adobe’s Technical Communication blog at http://blogs.adobe.com/techcomm/. The instructions for the script itself are in the April 23 post. The preliminary announcement was in the April 12 post.

The reason this script release is important is that it’s strategic. If you’re a RoboHelp shop but have wanted to try mobile output, you no longer have to buy and learn new authoring tools. Instead, mobile simply becomes one more output in a tool you already own. And if mobile turns out not to be what you need, there’s no money wasted on a dead-end tool - just abandon the mobile output and go back to your regular RoboHelp work.

I’ll be describing the feature set and some test results in an upcoming post.

Monday, April 12, 2010

"Beyond the Bleeding Edge" Returns

The "Bleeding Edge" returns to the STC Summit after a three year absence. If you're not familiar with the Bleeding Edge, it's a one- or two- session track in which speakers have 20 minutes to cover topics that appeared after the formal conference schedule was firmed up or just didn't fit into the formal conference presentation categories.

There will be one session this year, from 8 to 9:15 AM on Wednesday, with the following subjects and speakers:

iPhone, iPad, Android: A Quick Intro to Developing UA for Mobile Apps – Joe Welinske, WritersUA

Joe Welinske is currently working on the design of Help for iPhone, iPad and Android applications. While many mobile apps are simplistic, there is a rapidly growing list of applications with robust capabilities. Many of the more robust apps work in concert with web-based applications and knowledgebases. Joe's focus is on exposing the users to features that are not easily discovered. He is also improving user interface text. Word choices are extremely important with minimal screen real estate. In this session you will be exposed to the underlying iPhone and Android development environment. This brief overview can provide you with the basic tools to get started with mobile UA on your own or with your team.

Re-purposing Software You Already Have - An Example Using Mimic - Gretchen Hambright

What can one do with no money and a client who wants a new type of training?With only their brains and a spunky attitude, learn how the TetraTechAMT Training Team used MadCap Mimic to overcome this hurdle and create a new learning system to help make the skies over Washington, DC a safer place.

Search Engine Optimization: My Life with Spiders – Robert Armstrong

In this brief introduction to the world of Search Engine Optimization, we’ll lift the cover off the online marketing world and expose common practices that Technical Communicators should know about. We will discuss ways these practices can be adopted in the documentation world to improve content continuity, publication relevance, and even open doors to new career opportunities.

Hope to see you there...

Thursday, March 18, 2010

March 17 STC IDL SIG Tools Webinar - Notes and Answers to Questions

This post contains answers to questions that I received during my portion of the webinar, and some related notes. Some of the questions that came in apply to several of the tools that were presented so, if I missed your question, feel free to get in touch.

From KB:

Q: I will look the book up. Do you know if Adobe have a user's group for Captivate?

A: Yes – see http://forums.adobe.com/community/adobe_captivate

Q: is there a way to add a TOC into Captivate?
A: Yes, for an individual movie through the skin editor and for a group of movies through the aggregator.

Q: I found that the online captivate training is a little lacking. Can you recommend a good book to purchase to learn Captivate 4?

A: Look on Amazon for the books by Brenda Huettner and Kevin Siegel.

Q: Would like more on Captivate. Maybe another longer seminar with just Neil. A session dedicated to best practices on questions in Captivate would be a suggestion.
A: Something might be arranged thru the SIG at a later date, but that wouldn’t be for a while. In the meantime, if you’re near Philadelphia, I’m doing a half-day Captivate 4 workshop for them at their annual conference next Saturday -
http://www.stcpmc.org/index.php?section=66. I’m doing the same half-day workshop again at the annual conference in Dallas, and a regular session on Captivate as well. If you can’t get to any of those sessions, email me offline and we can look at other options.

From MA:

Q: Would you quickly run through the differences between version 3 and 4?

A: The main changes, IMO, are the addition of a “review” output based on AIR that lets reviewers comment electronically, project templates as a part of the app itself, variables, customization via “advanced actions” and Flash-based “widgets”, movie tables of contents, multi-movie tables of contents created the aggregator which replaces the old MenuBuilder. Take a look at the Captivate 4 page on the Adobe site for a complete listing.

Q: I have trouble getting true video files to play within the Captivate movie once it's published & moved to a different location (intranet)--can you speak to that?

A: I’d need to know more about the types of video files you’re using – “true video” – before I could take a stab at this. Feel free to email offline if you’d like.

Q: Can you speak more about the "game" usage?

A: Basically, introducing an element of play to the learning process. Beyond that, I’d need to know a bit more about what you’re thinking of.

From LS:

Q: Can we see a question slide inserted?

A: Done. LMK if you had any questions about what I did.

From JR:

Q: Will any of these publish to Silverlight, WMV or other Microsoft formats?

A: Captivate will not. MadCap Mimic will publish to Silverlight, and I think Camtasia will also but you’d have to verify that on the TechSmith site.

Again, feel free to email offline if necessary.

Wednesday, March 10, 2010

Thoughts on “Context-Sensitivity” and Dynamic Output Reconfiguration

I wrote the 2010 trends article for STC Intercom magazine. One of my predictions there was the emergence of “dynamically reconfigurable output,” which I took from an item in the News Digest section of an issue of ComputerWorld from around 2005. That item’s take was that XML, and xMetal in particular, could let us do cool things, such as creating online information that was sensitive to its “context.”

If you’re in tech comm, you may have been doing context sensitive online help systems – that know where you are in the application and display only relevant information – so what’s the big deal? But that wasn’t the idea of the item in ComputerWorld.

The idea there was online information that changed depending on its context, the example being an aircraft service manual whose content changed automatically based on whether the temperature was above or below freezing. (So this manual served two “audiences”.) Or consider smart phone and mobile device apps whose display mode shifts from portrait to landscape automatically, depending on whether the device is horizontal or vertical. (So this manual also serves two “audiences”.)

From tech comm’s perspective, this idea of “context sensitivity” has two interesting angles.

First is simply the idea that “context” means different things to different people and we in tech comm can no longer take that meaning for granted. (The article Context Matters by Beth Schultz, in the September 21/28 2009 issue of ComputerWorld, discussed “context” as the tagging of equipment in a hospital to define its location and make it easier to find. Anyone hired to do “context sensitive help” for that hospital who assumed the standard meaning of “context sensitive” would run the risk of creating the wrong project.)

Second, and odder, is the idea of dynamic reconfiguration as a means of serving different audiences, like below-/above-freezing or horizontal/vertical in the examples above. Such situations are easy to handle using today’s help authoring tools – create one project and, using conditionality and other single sourcing features, generate one version of the output for each audience. We then leave it to some other mechanism to direct users to the right version of the help depending on the circumstances – temperature, physical orientation, etc.

The problem with the multi-output approach is that it’s cumber- some. We have to create one output per audience, which can become challenging as the number of outputs grows. Better to create one output that can modify itself.

We’re slowly heading there. Mark Logic ran a webinar in October 2009 entitled “Dynamic Delivery Is Where It’s At: Custom Documentation From Multiple Formats” that offered some possibilities. And I’ve been told about various proprietary, code-level experiments in online help authoring. I’m just not aware of any developments at the help authoring tool level yet.

If you’re aware of any work on dynamic output reconfiguration using help authoring tools or as proprietary, code-level experiments that can be discussed, I’d love to hear about them on general principles, or possibly as an Intercom column or, if you can get to me between before March 19, possibly as a proposal for the Beyond the Bleeding Edge session at the annual STC conference.

Thursday, March 4, 2010

“Beyond the Bleeding Edge” is Back, and Looking for Proposals!

(for STC's annual Tech Comm Summit (aka annual conference) in Dallas, May 2 to 5.)

Sometime between now and May of 2010, might you…

…develop one online document conditionalized to be viewed on a desktop PC and an iPhone?

…create a document containing dynamically customizable content?

…create a hybrid document?

…perform a hard-dollar cost-justification of your documentation group’s work?

…or do something else that’s bleeding edge, and applicable to technical communication?

Many technical communicators are hard-put to keep up with the daily grind, let alone have time to look into emerging technologies. “Beyond the Bleeding Edge”, which debuted at the 1999 annual conference, addresses this by presenting summaries of technologies and methodologies that are too new or unusual to make it into traditional Summit sessions. After a three year hiatus, “Beyond the Bleeding Edge” is back and looking for presenters for the Tech Comm Summit in Dallas.

Is there a technology or methodology that you’d like to discuss? It can be:

· New… Are you creating online help that can change its contents depending on the outside air temperature?

· Existing, but fairly new to technical communicators, like physical context-sensitivity for mobile devices.

To be accepted, a “Bleeding Edge” topic must be fairly new as of early 2010. A “Bleeding Edge” presentation should be:

· Short – You’ll have about 20 minutes to cover your topic and take questions.
· Informal – Attendees prefer handouts but this is at your discretion.
· Level-appropriate – You can cover a topic at whatever technical level you consider necessary as long as you warn attendees what to expect.

If you enjoy new topics and like to discuss them, we want to hear from you. Send your proposals to Neil Perlin, Hyper/Word Services,
nperlin@nperlin.cnc.net or 978-657-5464 by March 19, 2010. There are only three slots this year, on Wednesday, May 5, from 8 to 9:15 AM. Slots fill up quickly, so don’t delay!