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…