Can You Use a Help Authoring Tool As A Content Management System?
An upcoming vendor-neutral webinar presented through MadCap Software...
If your documentation group is considering adopting a CMS, you may find that training, workflow, and cultural hurdles can make implementation harder than you think. And even a simple commercial CMS is far more expensive than traditional authoring tools, so those hurdles can get expensive.
Help authoring tools (HATs) like Flare and RoboHelp seem unrelated to CMSs, but HATs have gone far beyond their help authoring roots. They offer, or are starting to offer, features like repositories, version control, review management, content customization using conditionality and variables, and more. HATs today are effectively lightweight CMSs.
This means that if you're planning to move to a CMS, you may be able to use your current HAT to create a simulated CMS to find operational problems before buying the "real" CMS. You may even find that you can use your HAT as your CMS, saving a lot of money and upheaval. That's the subject of this webinar.
This webinar will take place on Thursday, March 12, from 9 AM to 10 AM PT. For information or to register, go to www1.gotomeeting.com/register/187845873. For information about other MadCap webinars, go to www.madcapsoftware.com/training/webinars.aspx
Monday, December 15, 2008
Saturday, November 8, 2008
AIR and Tech Comm
For those people who got tripped up by the webinar ID change on Thursday, November 6, here’s the AIR overview that we covered.
AIR (Adobe Integrated Runtime) is a fairly new output type from Adobe that’s a hybrid of a browser-based application and a desktop application. Adobe is implementing AIR across its product lines, and AIR is showing up outside Adobe as well, in the new release of MadCap Flare for example. Here, I’ll discuss AIR from one perspective – online help and documentation created using RoboHelp (and other tools like Flare).
First, a little history to put AIR in context…
In the late 1980s, Microsoft released Windows Help (“WinHelp”), the first mainstream online help format. One of WinHelp’s attributes was that it was “compiled”, combining all the topics in your online help or documentation into one file, the HLP, for distribution. (There was one more file, the CNT, but we can ignore that here.) Whether you had 1 topic or 1,000 in your help, they were distributed as one HLP file. This one-file model made WinHelp easy to distribute.
In 1997, Microsoft released WinHelp’s successor, HTML Help. It too was compiled into and distributed as one file (no CNT this time), the CHM. As with WinHelp, the one-file model made HTML Help easy to distribute. But this time, the model got tripped up by the spread of networks in general and the web in particular.
HTML Help wasn’t designed for a web-based world or non-Microsoft world. This meant it could only run on Windows PCs with IE, and could only run locally or from a network drive. As people began turning toward the web, and as other formats like Linux began to take off, HTML Help began hitting its limits. This happened pretty quickly; as early as mid-1997 people were complaining about how Microsoft-centric HTML Help was.
In late 1997 or early 1998, eHelp came out with a solution – WebHelp. WebHelp looked similar to HTML Help but didn’t bundle the topics into one distributable file. Instead, WebHelp kept topics as individual files that were managed by various control files. In effect, WebHelp was a web site with a documentation-like interface. This added great flexibility. WebHelp could run on almost any platform and browser and from any location (local, network drive, or server).
But it had some problems. Because it was not compiled, a WebHelp output had as many files as there were topics, graphics, and control files. A 1000-topic WebHelp system might have 1500 files, which made engineering and network management very unhappy. (“Fifteen-hundred files! For a help system!?”) Plus WebHelp places a heavy testing load on vendors since it has to be tested under and reconciled for different browsers and new versions of existing browsers.
So the ideal solution would be an output format that could run locally in order to reduce network traffic, that went back to the one-file model of WinHelp and HTML Help, that got away from the browser compatibility problem, and that was network aware… AIR.
When you convert an online help or documentation project to AIR, the AIR “packager” bundles the topics, graphics, and control files into one file with an AIR extension that runs locally. It avoids the browser compatibility problem by using its own viewer. It’s network-aware to handle updates. It has WebHelp-style attributes like the ability to use skins to customize the interface. It lets you create links to external targets like web pages and can run them in separate windows. Plus, because it’s running locally, it can take advantage of local features like file writes. For example…
The screen below shows a simple WebHelp project created in RoboHelp HTML 7. It has the usual tri-pane features, some formatting, and a link (“Show me how”) to a SWF movie created using Captivate.
For those people who got tripped up by the webinar ID change on Thursday, November 6, here’s the AIR overview that we covered.
AIR (Adobe Integrated Runtime) is a fairly new output type from Adobe that’s a hybrid of a browser-based application and a desktop application. Adobe is implementing AIR across its product lines, and AIR is showing up outside Adobe as well, in the new release of MadCap Flare for example. Here, I’ll discuss AIR from one perspective – online help and documentation created using RoboHelp (and other tools like Flare).
First, a little history to put AIR in context…
In the late 1980s, Microsoft released Windows Help (“WinHelp”), the first mainstream online help format. One of WinHelp’s attributes was that it was “compiled”, combining all the topics in your online help or documentation into one file, the HLP, for distribution. (There was one more file, the CNT, but we can ignore that here.) Whether you had 1 topic or 1,000 in your help, they were distributed as one HLP file. This one-file model made WinHelp easy to distribute.
In 1997, Microsoft released WinHelp’s successor, HTML Help. It too was compiled into and distributed as one file (no CNT this time), the CHM. As with WinHelp, the one-file model made HTML Help easy to distribute. But this time, the model got tripped up by the spread of networks in general and the web in particular.
HTML Help wasn’t designed for a web-based world or non-Microsoft world. This meant it could only run on Windows PCs with IE, and could only run locally or from a network drive. As people began turning toward the web, and as other formats like Linux began to take off, HTML Help began hitting its limits. This happened pretty quickly; as early as mid-1997 people were complaining about how Microsoft-centric HTML Help was.
In late 1997 or early 1998, eHelp came out with a solution – WebHelp. WebHelp looked similar to HTML Help but didn’t bundle the topics into one distributable file. Instead, WebHelp kept topics as individual files that were managed by various control files. In effect, WebHelp was a web site with a documentation-like interface. This added great flexibility. WebHelp could run on almost any platform and browser and from any location (local, network drive, or server).
But it had some problems. Because it was not compiled, a WebHelp output had as many files as there were topics, graphics, and control files. A 1000-topic WebHelp system might have 1500 files, which made engineering and network management very unhappy. (“Fifteen-hundred files! For a help system!?”) Plus WebHelp places a heavy testing load on vendors since it has to be tested under and reconciled for different browsers and new versions of existing browsers.
So the ideal solution would be an output format that could run locally in order to reduce network traffic, that went back to the one-file model of WinHelp and HTML Help, that got away from the browser compatibility problem, and that was network aware… AIR.
When you convert an online help or documentation project to AIR, the AIR “packager” bundles the topics, graphics, and control files into one file with an AIR extension that runs locally. It avoids the browser compatibility problem by using its own viewer. It’s network-aware to handle updates. It has WebHelp-style attributes like the ability to use skins to customize the interface. It lets you create links to external targets like web pages and can run them in separate windows. Plus, because it’s running locally, it can take advantage of local features like file writes. For example…
The screen below shows a simple WebHelp project created in RoboHelp HTML 7. It has the usual tri-pane features, some formatting, and a link (“Show me how”) to a SWF movie created using Captivate.
The next screen shows the same WebHelp converted to AIR. It keeps the tri-pane look and the link. The formatting got lost on conversion but can be recreated. This output also adds the “Resources” link at the top right which offers a drop-down list of external links. Note also that there are two pages open – Base Conversion and Hyper/Word Services – each in its own tab.
So the output would call for some minor tweaking (which should decline in later releases of AIR), but all in all, a good thing…
On the minus side, several things to consider:
AIR requires that developers (not viewers) have the JRE (Java RunTime Environment) on their PCs. This isn’t a big deal, but Sun’s download page can be a bit confusing.
AIR’s use of a proprietary viewer instead of a browser isn’t a big deal unless you support “zero-footprint” environments where viewers can’t download anything to their PCs. That means they won’t be able to download the viewer and thus can’t view the AIR file. This is a problem now but history suggests that it may lessen. For example, in 1997, WebHelp developers couldn’t be sure that viewers had any browser; today, it’s taken for granted. In 1999, developers couldn’t be sure that viewers would have the Flash Player; today, according to Adobe, 99% of all web-capable PCs have it. The AIR viewer is the latest in the “we’re not sure if users have it…” category but, if AIR takes off, the viewer may turn into one more default feature on users’ PCs.
AIR’s ability to use local PC features can be a security risk. Adobe is attempting to deal with this by requiring that developers create digital certificates for their AIR applications.
To sum up, I don’t know what the AIR’s future is but Adobe is making a big push for it and it’s definitely worth a look. For more information, go to www.adobe.com/ and search for AIR. To download the RoboHelp Packager for AIR, go to www.adobe.com/products/robohelp/robohelp-packager-for-air/
Friday, November 7, 2008
Answer to Mimic Question from DocTrain East Workshop on Nov. 1
Let's say that you create a text caption box in a Mimic movie frame, add some text that includes a variable, and size the text caption box so that its borders fit tightly around the text. Furthermore, let's say that the value of the variable is "ABC".
If you then change the value of the variable to a longer entry, such as "MadCap Software, Inc.", might some text be pushed outside the borders of the text caption box? Yes.
If so, how do I fix this to be sure that all the text fits inside the borders of the box? You have to adjust the size of each text caption box by hand. A better solution is to size each text caption box whose text contains that variable so that all the text will appear inside the box when the variable's value is set to the longest possible entry - e.g. "MadCap Software, Inc." This way, you know that all the text will appear in the box when you use shorter variable values. There will be some excess white space in the box, but you won't run the risk of having to modify the size of the box every time you change the value of the variable.
Let's say that you create a text caption box in a Mimic movie frame, add some text that includes a variable, and size the text caption box so that its borders fit tightly around the text. Furthermore, let's say that the value of the variable is "ABC".
If you then change the value of the variable to a longer entry, such as "MadCap Software, Inc.", might some text be pushed outside the borders of the text caption box? Yes.
If so, how do I fix this to be sure that all the text fits inside the borders of the box? You have to adjust the size of each text caption box by hand. A better solution is to size each text caption box whose text contains that variable so that all the text will appear inside the box when the variable's value is set to the longest possible entry - e.g. "MadCap Software, Inc." This way, you know that all the text will appear in the box when you use shorter variable values. There will be some excess white space in the box, but you won't run the risk of having to modify the size of the box every time you change the value of the variable.
Monday, October 13, 2008
Chrome - the Google vs. Microsoft War Heats Up...
After a three-month hiatus, the blog is back...
In February, I wrote a column called "The $44.6 Billion Paradigm Shift" for STC's Intercom magazine. The column looked at Microsoft's aborted attempt to buy Yahoo and what that meant strategically. The gist of the column was that Microsoft saw a long-term threat from Google as the latter works to shift applications from the desktop to the web. Such a shift would make Microsoft's domination of the desktop irrelevant and cause a disastrous cut in Microsoft's revenue stream. (If you don't need the desktop, you don't need Windows...)
The latest sally in this war comes from Google with its release of Chrome in early September. On the surface, Chrome is just a browser. But it also offer an environment in which to run applications like Google Docs, without going through Windows. It has a ways to go today; we're looking at v.1 or, more accurately, a beta v.1 that really uses the Chrome interface to launch the application, which then opens in your regular browser. But the idea is likely to be refined in later releases, just as Microsoft went through several early releases of Windows before getting it (largely) right. If you remember the infamous Microsoft Bob, you get the idea.
I'll discuss Chrome in more detail in my Bleeding Edge column for STC's Intercom. If you're not an STC member but would like a copy of the column, email me at the beginning of November.
One side note about Chrome - how does it work with the output from popular help authoring tools. In a totally unscientific test, I tried viewing two different WebHelp projects through Chrome, one created in RoboHelp 7, the other in Flare 3.1 and then imported into Flare 4. The results?
Everything seemed to work in the Flare project - graphics, links, formatting, and navigation tabs (TOC, Index, etc.)
Almost everything seemed to work in the RoboHelp project. The graphics, links, and formatting all worked, which makes sense since they're basically standard HTML. But I ran into two problems. First, when I opened a topic containing a Captivate movie, the movie display box appeared but a message indicated that I needed to download the Flash player. I did and the movie ran fine, but I'm not sure why I had to download the player since it was already on the machine. More serious was the fact that the navigation tabs displayed but the TOC and Index tabs were empty. More research on the horizon...
After a three-month hiatus, the blog is back...
In February, I wrote a column called "The $44.6 Billion Paradigm Shift" for STC's Intercom magazine. The column looked at Microsoft's aborted attempt to buy Yahoo and what that meant strategically. The gist of the column was that Microsoft saw a long-term threat from Google as the latter works to shift applications from the desktop to the web. Such a shift would make Microsoft's domination of the desktop irrelevant and cause a disastrous cut in Microsoft's revenue stream. (If you don't need the desktop, you don't need Windows...)
The latest sally in this war comes from Google with its release of Chrome in early September. On the surface, Chrome is just a browser. But it also offer an environment in which to run applications like Google Docs, without going through Windows. It has a ways to go today; we're looking at v.1 or, more accurately, a beta v.1 that really uses the Chrome interface to launch the application, which then opens in your regular browser. But the idea is likely to be refined in later releases, just as Microsoft went through several early releases of Windows before getting it (largely) right. If you remember the infamous Microsoft Bob, you get the idea.
I'll discuss Chrome in more detail in my Bleeding Edge column for STC's Intercom. If you're not an STC member but would like a copy of the column, email me at the beginning of November.
One side note about Chrome - how does it work with the output from popular help authoring tools. In a totally unscientific test, I tried viewing two different WebHelp projects through Chrome, one created in RoboHelp 7, the other in Flare 3.1 and then imported into Flare 4. The results?
Everything seemed to work in the Flare project - graphics, links, formatting, and navigation tabs (TOC, Index, etc.)
Almost everything seemed to work in the RoboHelp project. The graphics, links, and formatting all worked, which makes sense since they're basically standard HTML. But I ran into two problems. First, when I opened a topic containing a Captivate movie, the movie display box appeared but a message indicated that I needed to download the Flash player. I did and the movie ran fine, but I'm not sure why I had to download the player since it was already on the machine. More serious was the fact that the navigation tabs displayed but the TOC and Index tabs were empty. More research on the horizon...
Monday, July 28, 2008
Remaining Questions From Remote Flare Course
Sorry about the delay, folks. Here are the answers to the remaining questions…
How to control the indent of a table – To set a global indent, open the Stylesheet Editor, select the tr style, open the Box properties group, and set the indent by using the margin-left property. To set an indent for one table, or one group of tables, create a new style class under the tr style, such as “table indent style 1” or the like, then select the new style, open the Box properties group, and set the indent by using the margin-left property.
Find Results window not displaying – If you recall, the Find Results window didn’t open when I ran a search in the advanced course. This was due to some undetermined layout setting. To fix this, reset your layout to the default (Window > Layouts > Reset Window Layout…) and try the search again. The Find Results window should display perfectly at the bottom of the screen.
Is there a “Keep With Next” or “Keep With Previous” setting for print out- put to prevent two page elements from splitting across a page break, such as keeping a paragraph and a numbered list together? – Yes, but it’s not labelled as such. In the Stylesheet editor, open the PrintSupport properties group for the style that you’re formatting and select either the always or avoid value, as needed, for either the page-break-before or page-break-after property, as needed.
Sorry about the delay, folks. Here are the answers to the remaining questions…
How to control the indent of a table – To set a global indent, open the Stylesheet Editor, select the tr style, open the Box properties group, and set the indent by using the margin-left property. To set an indent for one table, or one group of tables, create a new style class under the tr style, such as “table indent style 1” or the like, then select the new style, open the Box properties group, and set the indent by using the margin-left property.
Find Results window not displaying – If you recall, the Find Results window didn’t open when I ran a search in the advanced course. This was due to some undetermined layout setting. To fix this, reset your layout to the default (Window > Layouts > Reset Window Layout…) and try the search again. The Find Results window should display perfectly at the bottom of the screen.
Is there a “Keep With Next” or “Keep With Previous” setting for print out- put to prevent two page elements from splitting across a page break, such as keeping a paragraph and a numbered list together? – Yes, but it’s not labelled as such. In the Stylesheet editor, open the PrintSupport properties group for the style that you’re formatting and select either the always or avoid value, as needed, for either the page-break-before or page-break-after property, as needed.
Tuesday, July 22, 2008
First Issue From the 7/21-7/22 Advanced Flare Course
Re the exercise on page 103 about finding and removing unused style classes from a CSS - I looked in the original dept_styles.css file, in the Files folder, and it does contain the p.temporary class. This means that I probably accidentally deleted p.temporary from the css in the project when I was moving other style classes out from under the Print Medium. So you should have found p.temporary in the dept_styles.css file that you imported into the project and should have been able to delete it per the exercise.
More to come over the next few days.
Re the exercise on page 103 about finding and removing unused style classes from a CSS - I looked in the original dept_styles.css file, in the Files folder, and it does contain the p.temporary class. This means that I probably accidentally deleted p.temporary from the css in the project when I was moving other style classes out from under the Print Medium. So you should have found p.temporary in the dept_styles.css file that you imported into the project and should have been able to delete it per the exercise.
More to come over the next few days.
Sunday, July 20, 2008
A Word and Framemaker File Import Peculiarity in MadCap Flare
If you've ever imported Word or Frame files into Flare, you may have tripped over a peculiarity in Flare's Word Import Editor and Frame Import Editor. It has to do with how two features in these editors can conflict and produce often totally unpredictable results.
The first feature is the New Topic Styles tab. This feature scans the file to import and lists all head styles in that file. You can then tell Flare to split the file by splitting on specific head styles. For example, if Flare finds head 1, 2, and 3 in the incoming file and you specify head 1 and 2 on which to split, Flare creates a new topic every time it finds text in head 1 or 2 style. Text in head 3 style remains a part of the head 2-level-based topic that contains it. So far, so good.
The second feature is the Options tab. This feature scans the file to import, counts the number of characters in it, then lets you split the file at character X. The default length is 10,000 characters, with a default of 1,000 in the split document. For example, if a file contains 10,001 characters, Flare will not split this document because it exceeds the minimum length to be split (10,000 characters) but does not meet the minimum length required for the file to be split out (1,000 characters). If the a file contains 11,001 characters, then it meets both minimums (10,000 characters overall plus 1,000 characters for the split). The result is two topics, one of 10,000 characters and one of 1,001 characters.
The result is actually a bit more complex since there's a risk of the split occurring in the middle of a paragraph. So Flare actually splits the file at the whole paragraph nearest the split point. As you might imagine, it's hard to predict where the file will be split. Ignoring this issue, however, the split-on-number-of-characters feature is pretty straightforward. So what's the problem that I mentioned at the beginning?
The problem is that this split-on-number-of-characters feature is turned on by default. If you look at the Options tab on the Word or Frame Import Editor, you'll see that the two "Add..." options, the "Split..." option, and the "Avoid Creating..." option are all selected. The result is that if you also use the Heading style options on the New Topic Styles tab to split incoming files, you have absolutely no idea how Flare will create the new topics.
So, if you want to use the Heading style options on the New Topic Styles tab to split incoming files, go to the Options tab first and deselect the two "Add..." options, the "Split..." option, and the "Avoid Creating..." option. Then you should be fine.
If you've ever imported Word or Frame files into Flare, you may have tripped over a peculiarity in Flare's Word Import Editor and Frame Import Editor. It has to do with how two features in these editors can conflict and produce often totally unpredictable results.
The first feature is the New Topic Styles tab. This feature scans the file to import and lists all head styles in that file. You can then tell Flare to split the file by splitting on specific head styles. For example, if Flare finds head 1, 2, and 3 in the incoming file and you specify head 1 and 2 on which to split, Flare creates a new topic every time it finds text in head 1 or 2 style. Text in head 3 style remains a part of the head 2-level-based topic that contains it. So far, so good.
The second feature is the Options tab. This feature scans the file to import, counts the number of characters in it, then lets you split the file at character X. The default length is 10,000 characters, with a default of 1,000 in the split document. For example, if a file contains 10,001 characters, Flare will not split this document because it exceeds the minimum length to be split (10,000 characters) but does not meet the minimum length required for the file to be split out (1,000 characters). If the a file contains 11,001 characters, then it meets both minimums (10,000 characters overall plus 1,000 characters for the split). The result is two topics, one of 10,000 characters and one of 1,001 characters.
The result is actually a bit more complex since there's a risk of the split occurring in the middle of a paragraph. So Flare actually splits the file at the whole paragraph nearest the split point. As you might imagine, it's hard to predict where the file will be split. Ignoring this issue, however, the split-on-number-of-characters feature is pretty straightforward. So what's the problem that I mentioned at the beginning?
The problem is that this split-on-number-of-characters feature is turned on by default. If you look at the Options tab on the Word or Frame Import Editor, you'll see that the two "Add..." options, the "Split..." option, and the "Avoid Creating..." option are all selected. The result is that if you also use the Heading style options on the New Topic Styles tab to split incoming files, you have absolutely no idea how Flare will create the new topics.
So, if you want to use the Heading style options on the New Topic Styles tab to split incoming files, go to the Options tab first and deselect the two "Add..." options, the "Split..." option, and the "Avoid Creating..." option. Then you should be fine.
Friday, July 11, 2008
Why Migrating From Word To An XML-Based Document Authoring Tool Won’t Be Easy …
Every once in a while, you run into a situation that supports a position of yours to a tee. Here’s one…
XML-based authoring tool vendors claim their products are getting easier to use with each release. They’re right. Comparing today’s xMetal to the original is like comparing night and day. However, my position is that there are four unfortunate corollaries to this trend that are going to make life tough for many doc groups in the next few years.
1 - As the tools get better, the need for authors to understand the underlying technologies is apparently declining. For example, if a tool lets you define styles by using a dialog box, do you need to know CSS coding, or even what CSS is? Which brings us to…
2 - As the tools get easier to use, there’s a sense in many companies that there's less need for training.
3 - XML-based authoring tool vendors talk about authors using their tools to create content much the way authors do now with Word. The implication is that migration from Word to an XML-based authoring tool is conceptually similar and thus shouldn’t be too difficult.
4 - The XML-based authoring world is very different from the Word world, and those differences are going to create some unfortunate assumptions.
The result of these corollaries is a lot of confusion, which brings up that situation I mentioned. (Before I proceed, let me make clear that what follows is not a slap at xMetal. It’s just that a very basic feature of xMetal illustrates the four corollaries perfectly.)
To create a new document in xMetal, you select File > New.
The first decision point, and problem, is whether to create a document from a template or a blank document. It’s confusing since any new document is “blank.” What this is really asking is whether to create a new document based on a DITA template or a non-DITA template, specifically XML or SGML. If authors understand the difference between DITA, XML, and SGML, it’s an easy decision. But if authors don’t understand the difference, haven’t been trained, and are thinking in Word terms, the very first step in a new project is confusing.
The second decision point, and problem, is when you decide that the General tab options make sense since you want to create an XML document rather than a DITA document. The help even says to choose the DTD, schema, or rules file for the document you want to create. But if you select the Blank Well-Formed XML Document option, there’s no place to choose the DTD, schema, or rules file. You’re just thrown into a new document. But if you select the Blank XML Document option, xMetal asks you to select the DTD, schema, or rules file. So there’s something different between the Blank Well-Formed XML Document and Blank XML Document options, but what? And isn’t a document that’s well-formed, whatever that is, better than a document that’s apparently not well-formed? And why would any tool let you create one? It all makes sense once you understand that the Blank XML Document option is really the Blank ‘Valid’ XML Document option, if you can find someone to explain this. If not, authors coming over from Word will again be lost on their first step.
The solution, of course, is to understand XML’s underlying technologies, ideally through directed training as opposed to floundering through a new technology. This may seem like a lot to read into one menu selection, but there are many assumptions behind that one menu selection that, if unaddressed, will leave new authors lost and frustrated.
Every once in a while, you run into a situation that supports a position of yours to a tee. Here’s one…
XML-based authoring tool vendors claim their products are getting easier to use with each release. They’re right. Comparing today’s xMetal to the original is like comparing night and day. However, my position is that there are four unfortunate corollaries to this trend that are going to make life tough for many doc groups in the next few years.
1 - As the tools get better, the need for authors to understand the underlying technologies is apparently declining. For example, if a tool lets you define styles by using a dialog box, do you need to know CSS coding, or even what CSS is? Which brings us to…
2 - As the tools get easier to use, there’s a sense in many companies that there's less need for training.
3 - XML-based authoring tool vendors talk about authors using their tools to create content much the way authors do now with Word. The implication is that migration from Word to an XML-based authoring tool is conceptually similar and thus shouldn’t be too difficult.
4 - The XML-based authoring world is very different from the Word world, and those differences are going to create some unfortunate assumptions.
The result of these corollaries is a lot of confusion, which brings up that situation I mentioned. (Before I proceed, let me make clear that what follows is not a slap at xMetal. It’s just that a very basic feature of xMetal illustrates the four corollaries perfectly.)
To create a new document in xMetal, you select File > New.
The first decision point, and problem, is whether to create a document from a template or a blank document. It’s confusing since any new document is “blank.” What this is really asking is whether to create a new document based on a DITA template or a non-DITA template, specifically XML or SGML. If authors understand the difference between DITA, XML, and SGML, it’s an easy decision. But if authors don’t understand the difference, haven’t been trained, and are thinking in Word terms, the very first step in a new project is confusing.
The second decision point, and problem, is when you decide that the General tab options make sense since you want to create an XML document rather than a DITA document. The help even says to choose the DTD, schema, or rules file for the document you want to create. But if you select the Blank Well-Formed XML Document option, there’s no place to choose the DTD, schema, or rules file. You’re just thrown into a new document. But if you select the Blank XML Document option, xMetal asks you to select the DTD, schema, or rules file. So there’s something different between the Blank Well-Formed XML Document and Blank XML Document options, but what? And isn’t a document that’s well-formed, whatever that is, better than a document that’s apparently not well-formed? And why would any tool let you create one? It all makes sense once you understand that the Blank XML Document option is really the Blank ‘Valid’ XML Document option, if you can find someone to explain this. If not, authors coming over from Word will again be lost on their first step.
The solution, of course, is to understand XML’s underlying technologies, ideally through directed training as opposed to floundering through a new technology. This may seem like a lot to read into one menu selection, but there are many assumptions behind that one menu selection that, if unaddressed, will leave new authors lost and frustrated.
Saturday, June 21, 2008
Friday, June 20, 2008
Adobe AIR
Since Adobe introduced AIR, there’s been a lot of discussion about what it is and why to use it. I’ve also been asked how it applies to RoboHelp specifically. The Adobe web site describes AIR, but I think the discussion is aimed a bit too much at developers and not enough at RoboHelp authors, so here’s my short initial take on what AIR is in general and for RoboHelp specifically.
In general…
AIR, Adobe Integrated Runtime, is an output format with characteristics of both web-based and desktop applications. It’s web-aware but doesn’t run in a browser. Instead, it runs like a desktop application, which lets it take advantage of desktop features like local file storage. Yet because it’s web-aware, it can search the web for updates if users have an internet connection and update itself as needed. Adobe has stated that it plans to implement AIR across its product line, essentially creating a new output format.
For RoboHelp…
The Microsoft HTML Help output format (CHM) is an old (pre-‘97) and increasingly constrained format that looks increasingly antiquated in an increasingly webby world. It will be around for a long time, just as WinHelp has been around since it was unofficially put to sleep in ‘97, but I consider it a dying format.
However, HTML Help has one great attribute – it’s compiled. No matter whether a project contains one topic or a thousand, they’ll all be encapsulated into one distributable CHM file. IT managers like this because they only have to distribute one file. That one-file model is increasingly out of place in a web-oriented world, but its simplicity is a virtue.
In contrast, WebHelp, created by eHelp (original vendor of RoboHelp) in ‘97/’98, is not compiled. If a project contains a thousand topics, you have to distribute one thousand files – slightly more counting the control files. (This sounds difficult but it’s easy since RoboHelp puts all the files in one WebHelp folder. You just distribute that folder.) This makes WebHelp more efficient for web-based distribution because it acts like a web site. If users call for one topic, they get that one topic rather than all one thousand as they would with the CHM. However, IT managers often don’t like having to upload those thousand-plus files to a server.
The RoboHelp Packager for Adobe AIR tries to get the best of both formats. (To download beta 2, see http://labs.adobe.com/technologies/robohelp/.)
Like HTML Help, the Packager encapsulates all the distributable files in one AIR file. This means IT only has to deal with one file rather than hundreds or thousands as it does with WebHelp. (Even though those files are contained in a single WebHelp folder, they still have to be distributed.) For many IT managers, that’s a big benefit by itself.
Once you output to AIR, you get several other options as well.
You can apply skins, a la WebHelp. However, the skins are more flexible. For example, you can add a Resources button on the toolbar with links to other web pages. If you select one of those links, the target page opens in the AIR window in its own tab. This lets users keep the help file and other web pages open at the same time and access them quickly by just selecting the desired tab.
The output should look consistent on different platforms and operating systems. (I’d want to see a greater base of experience about this before accepting the idea wholeheartedly since different platforms and operating systems often have odd twists. However, since the output is not running in a browser, the browser display differences that we often see shouldn’t be an issue.
You can give users the ability to comment on the output, lending a Web 2.0 air to RoboHelp for the first time.
What do we have to do to make AIR work on users’ PCs? According to the AIR help, users must have the Adobe AIR runtime environment installed on their PCs. This seems like a straightforward download and installation. However, compared to the simple Flash Viewer installation procedure that many users are accustomed to, the AIR runtime installation is going to look more difficult and may slow acceptance of AIR until the runtime installation gets simpler.
I’ll add more as the RoboHelp Packager for Adobe AIR firms up.
Since Adobe introduced AIR, there’s been a lot of discussion about what it is and why to use it. I’ve also been asked how it applies to RoboHelp specifically. The Adobe web site describes AIR, but I think the discussion is aimed a bit too much at developers and not enough at RoboHelp authors, so here’s my short initial take on what AIR is in general and for RoboHelp specifically.
In general…
AIR, Adobe Integrated Runtime, is an output format with characteristics of both web-based and desktop applications. It’s web-aware but doesn’t run in a browser. Instead, it runs like a desktop application, which lets it take advantage of desktop features like local file storage. Yet because it’s web-aware, it can search the web for updates if users have an internet connection and update itself as needed. Adobe has stated that it plans to implement AIR across its product line, essentially creating a new output format.
For RoboHelp…
The Microsoft HTML Help output format (CHM) is an old (pre-‘97) and increasingly constrained format that looks increasingly antiquated in an increasingly webby world. It will be around for a long time, just as WinHelp has been around since it was unofficially put to sleep in ‘97, but I consider it a dying format.
However, HTML Help has one great attribute – it’s compiled. No matter whether a project contains one topic or a thousand, they’ll all be encapsulated into one distributable CHM file. IT managers like this because they only have to distribute one file. That one-file model is increasingly out of place in a web-oriented world, but its simplicity is a virtue.
In contrast, WebHelp, created by eHelp (original vendor of RoboHelp) in ‘97/’98, is not compiled. If a project contains a thousand topics, you have to distribute one thousand files – slightly more counting the control files. (This sounds difficult but it’s easy since RoboHelp puts all the files in one WebHelp folder. You just distribute that folder.) This makes WebHelp more efficient for web-based distribution because it acts like a web site. If users call for one topic, they get that one topic rather than all one thousand as they would with the CHM. However, IT managers often don’t like having to upload those thousand-plus files to a server.
The RoboHelp Packager for Adobe AIR tries to get the best of both formats. (To download beta 2, see http://labs.adobe.com/technologies/robohelp/.)
Like HTML Help, the Packager encapsulates all the distributable files in one AIR file. This means IT only has to deal with one file rather than hundreds or thousands as it does with WebHelp. (Even though those files are contained in a single WebHelp folder, they still have to be distributed.) For many IT managers, that’s a big benefit by itself.
Once you output to AIR, you get several other options as well.
You can apply skins, a la WebHelp. However, the skins are more flexible. For example, you can add a Resources button on the toolbar with links to other web pages. If you select one of those links, the target page opens in the AIR window in its own tab. This lets users keep the help file and other web pages open at the same time and access them quickly by just selecting the desired tab.
The output should look consistent on different platforms and operating systems. (I’d want to see a greater base of experience about this before accepting the idea wholeheartedly since different platforms and operating systems often have odd twists. However, since the output is not running in a browser, the browser display differences that we often see shouldn’t be an issue.
You can give users the ability to comment on the output, lending a Web 2.0 air to RoboHelp for the first time.
What do we have to do to make AIR work on users’ PCs? According to the AIR help, users must have the Adobe AIR runtime environment installed on their PCs. This seems like a straightforward download and installation. However, compared to the simple Flash Viewer installation procedure that many users are accustomed to, the AIR runtime installation is going to look more difficult and may slow acceptance of AIR until the runtime installation gets simpler.
I’ll add more as the RoboHelp Packager for Adobe AIR firms up.
Wednesday, May 21, 2008
Microformats
In April, I gave a workshop for the Boston STC on the issue of doing structured authoring without using DITA or Frame. In the workshop, I happened to mention a technology called microformats which several people asked me to define during and after the workshop. I did but, in retrospect, decided that I wasn't satisfied with the answer that I gave. So, here's a better definition that also has a number of additional ramifications.
Microformats use elements from existing languages or standards, like HTML, to mark up web content in such a way as to add semantic information to that content for use in Web 2.0, without having to adopt new languages or standards. Basically, microformats re-use existing features of current languages and standards.
There are several issues tied up in this definition. Let's take a look at two big ones.
- Existing languages or standards... - Every language or standard has a number of widely-used features and an often much larger number of little-known features. The latter often go unused or unnoticed. For example, the rel attribute of the link tag points to the location of the CSS that we attach to a topic in a help system, but rel often goes unnoticed unless you delve into the code. Yet rel is actually pretty flexible, offering a bunch of pre-defined values *and* the ability to define your own. This can get pretty esoteric, but it does not require you to buy and learn new software, just new ways to work what you already have.
- Semantic... - HTML tags like h1 are presentational rather than semantic. In other words, applying h1 to text tells us how to display that text but not what it is. For example, consider an online book store that uses HTML to mark up its listings. We could create a book listing and use h1 for the book title and h2 for the name of the author. We can then format the display by specifying the style attributes for h1 and h2, but we have no way of knowing that h1 is actually the book title and h2 is the author's name - e.g. the semantics of the information. XML lets us fix this by creating our own, semantically-definitive tags, such as creating and using tags called and rather than h1 and h2. But HTML already has elements that carry semantic information, such as the "cite" element that lets us identify a block of text as a citation. In other words, we may well be able to add semantic information without having to move to XML or DITA.
For a detailed overview of microformats, I recommend Microformats: Empowering Your Markup for Web 2.0 by John Allsopp, published by friendsof. In fact, I recommend reading the book even if you never plan to use microformats because of two other useful aspects of the book.
The first is the author's discussion of structural and semantic HTML in chapter 3. Here, he discusses some of the more rigorous programmatic aspects of HTML, how they're implemented, and why they're important for the long run.
The second is the nuggets sprinkled throughout the book, such as this one on why XML is important for RSS feeds.
"...RSSs are also XML-based languages, meaning that feeds must at least be well-formed..."
(from Microformats: Empowering Your Markup for Web 2.0, page 226.)
Why does this matter for technical communication? Today, most material produced by technical communicators is self-contained - e.g. a help system or user manual produced by one developer. But the web already has features like RSS feeds and aggregators that may be just as useful for technical communication. What the nugget above is saying is that RSS feeds and aggregators will most likely require XML, which will require a move away from HTML and the adoption of authoring tools that produce content that's at least well-formed if not valid. ("well-formed" and "valid" in the programmatic sense of following XML syntax rules.)
The book assumes familiarity with HTML, XML, IETF, and other acronyms and is very dense, but it's a quick read if you just look at a few code samples to get the idea and focus instead on the larger issues of programmatic rigor. Highly recommended.
In April, I gave a workshop for the Boston STC on the issue of doing structured authoring without using DITA or Frame. In the workshop, I happened to mention a technology called microformats which several people asked me to define during and after the workshop. I did but, in retrospect, decided that I wasn't satisfied with the answer that I gave. So, here's a better definition that also has a number of additional ramifications.
Microformats use elements from existing languages or standards, like HTML, to mark up web content in such a way as to add semantic information to that content for use in Web 2.0, without having to adopt new languages or standards. Basically, microformats re-use existing features of current languages and standards.
There are several issues tied up in this definition. Let's take a look at two big ones.
- Existing languages or standards... - Every language or standard has a number of widely-used features and an often much larger number of little-known features. The latter often go unused or unnoticed. For example, the rel attribute of the link tag points to the location of the CSS that we attach to a topic in a help system, but rel often goes unnoticed unless you delve into the code. Yet rel is actually pretty flexible, offering a bunch of pre-defined values *and* the ability to define your own. This can get pretty esoteric, but it does not require you to buy and learn new software, just new ways to work what you already have.
- Semantic... - HTML tags like h1 are presentational rather than semantic. In other words, applying h1 to text tells us how to display that text but not what it is. For example, consider an online book store that uses HTML to mark up its listings. We could create a book listing and use h1 for the book title and h2 for the name of the author. We can then format the display by specifying the style attributes for h1 and h2, but we have no way of knowing that h1 is actually the book title and h2 is the author's name - e.g. the semantics of the information. XML lets us fix this by creating our own, semantically-definitive tags, such as creating and using tags called
For a detailed overview of microformats, I recommend Microformats: Empowering Your Markup for Web 2.0 by John Allsopp, published by friendsof. In fact, I recommend reading the book even if you never plan to use microformats because of two other useful aspects of the book.
The first is the author's discussion of structural and semantic HTML in chapter 3. Here, he discusses some of the more rigorous programmatic aspects of HTML, how they're implemented, and why they're important for the long run.
The second is the nuggets sprinkled throughout the book, such as this one on why XML is important for RSS feeds.
"...RSSs are also XML-based languages, meaning that feeds must at least be well-formed..."
(from Microformats: Empowering Your Markup for Web 2.0, page 226.)
Why does this matter for technical communication? Today, most material produced by technical communicators is self-contained - e.g. a help system or user manual produced by one developer. But the web already has features like RSS feeds and aggregators that may be just as useful for technical communication. What the nugget above is saying is that RSS feeds and aggregators will most likely require XML, which will require a move away from HTML and the adoption of authoring tools that produce content that's at least well-formed if not valid. ("well-formed" and "valid" in the programmatic sense of following XML syntax rules.)
The book assumes familiarity with HTML, XML, IETF, and other acronyms and is very dense, but it's a quick read if you just look at a few code samples to get the idea and focus instead on the larger issues of programmatic rigor. Highly recommended.
Saturday, May 3, 2008
How We Got Here - A History of DITA (and other things that we see today, not necessarily DITA-related)
Technical communication tends to focus either on the present (gotta finish the project...) or on the future (what's the next big thing and how might it affect me). The past sometimes gets lost. Yet if we get beyond the "When I was your age..." stories, the past can often teach us a lot - why did a particular technology or tool or methodology fail ten years ago, for example - letting us draw parallels to something we're doing today. And if nothing else, the past is intellectually interesting. How did we get to where we are today...
On that note, I recommend reading a history of DITA, written by long-time DITA consultant (among many other things) Bob Doyle. The article, available at http://dita.xml.org/book/history-of-dita describes the history of DITA but, in a larger sense, describes the evolution of today's technical communication field. Highly recommended.
Technical communication tends to focus either on the present (gotta finish the project...) or on the future (what's the next big thing and how might it affect me). The past sometimes gets lost. Yet if we get beyond the "When I was your age..." stories, the past can often teach us a lot - why did a particular technology or tool or methodology fail ten years ago, for example - letting us draw parallels to something we're doing today. And if nothing else, the past is intellectually interesting. How did we get to where we are today...
On that note, I recommend reading a history of DITA, written by long-time DITA consultant (among many other things) Bob Doyle. The article, available at http://dita.xml.org/book/history-of-dita describes the history of DITA but, in a larger sense, describes the evolution of today's technical communication field. Highly recommended.
Monday, April 28, 2008
If You Plan To Attend My Captivate or RoboHelp Workshops at DocTrain West...
Please follow these setup instructions.
For the Captivate 3 workshop:
Please install and test at least two working days before the workshop.
Hardware:
· Adobe Flash® Player 7 or later
· Captivate 3. To download a trial copy, go to www.adobe.com/products/captivate/, click the Download Free Trial link, and follow the instructions on the screen. The trial version is not supported on Windows 2000.
· Pentium III 300 MHz or above.
· 256 MB RAM or more.
· 400 MB disk space or more.
· Windows 2000 SP 4 or later, preferably XP.
· Word 2000, XP, or 2003.
· IE 6 and any other browser that you support.
· Adobe Flash® Player 7 or later.
· CD/DVD or USB drive.
· RoboHelp 7. To download a trial copy, go to www.adobe.com/products/robohelp/ and follow the setup instructions. Accept all defaults to install RoboHelp. You do not have to install RoboPDF or RoboSource Control unless you want to try them after the workshop.
If you have any problems, please contact me immediately.
Please follow these setup instructions.
For the Captivate 3 workshop:
Please install and test at least two working days before the workshop.
Hardware:
· Intel® Pentium 4, Intel Centrino®, Intel Xeon®, or Intel Core™ Duo (or compatible) processor
· Microsoft® Windows XP with Service Pack 2, Windows 2000 with Service Pack 2, or Windows Vista™ Home Premium, Business, Ultimate, or Enterprise (certified for 32-bit editions)
· 512 MB of RAM (1GB recommended)
· 700 MB of available hard-disk space after installation
· CD/DVD or USB drive
· 800 X 600 screen resolution (1024 x 768 recommended)
Software:
· Microsoft IE 6 or later· Adobe Flash® Player 7 or later
· Captivate 3. To download a trial copy, go to www.adobe.com/products/captivate/, click the Download Free Trial link, and follow the instructions on the screen. The trial version is not supported on Windows 2000.
If you have any problems, please contact me immediately.
For the RoboHelp 7 workshop:
Please install and test at least two working days before the workshop.· Pentium III 300 MHz or above.
· 256 MB RAM or more.
· 400 MB disk space or more.
· Windows 2000 SP 4 or later, preferably XP.
· Word 2000, XP, or 2003.
· IE 6 and any other browser that you support.
· Adobe Flash® Player 7 or later.
· CD/DVD or USB drive.
· RoboHelp 7. To download a trial copy, go to www.adobe.com/products/robohelp/ and follow the setup instructions. Accept all defaults to install RoboHelp. You do not have to install RoboPDF or RoboSource Control unless you want to try them after the workshop.
If you have any problems, please contact me immediately.
Sunday, April 20, 2008
Unusual Uses for Captivate et al
Visual help authoring tools like Captivate, Camtasia, and Mimic were initially designed for creating software-related “movies” showing how to use features or perform tasks in a piece of software. They’re great tools – easy to use, cheap enough (most in the $299 to $699 range) that they pose a real threat to “big” tools like Authorware and Toolbook, and flexible. That flexibility is one of the best features because it leads authors to use these tools in ways that the vendors perhaps never intended, or even thought of. For example:
Role-playing simulations – The tools make it easy to create role-playing sims like sales or HR training. Captivate 2 came with a sample that tested your skills as an automobile sales rep, and Captivate 3 comes with one that teaches interviewing skills. But these sims can cover almost any topic; in 2007, I created a sim that showed how to determine whether a baby’s diaper needed to be changed. (With apologies to my grand-niece Eleanor Ruby, aka Ellie Belly.)
Games – Your first response to the idea of using these tools to create games may be no. That was mine, until I realized that it simply depends on how you define “game”. In some ways, interactive role-playing or software sims are games – the difference lies largely in the tone. And these tools make it easy to create scorable “games.”
Comics – In early ‘07, an attendee in my Captivate class asked what I thought of the idea of using the tool to create anime-style comics. I was going to say that it didn’t seem appropriate until I remembered the evolution of my thoughts about using Captivate to create games. Depending on what you want to do, I see no reason why not to use these tools to create anime, or other types of comics.
One serendipitous thought about where to get graphics for your animated comics. Silke Fleischer, Adobe’s product manager for Captivate, mentioned in her blog (http://blogs.adobe.com/silke.fleischer/) the idea of creating a Second Life (http://secondlife.com/) account and capturing the characters. This may be a lot of work initially if you can’t find someone who’s already using Second Life, but once you learn the software and create character(s), you effectively have your own animation studio.
Usability test recording – Less odd but more useful, these tools let you create your own usability test recording tools. One of the problems that I often hear regarding usability testing is the cost of the testing facility in general and tools in particular. In response to one question, I figured out how to use Captivate as a tool to record the results of software usability tests. It’s not perfect, but it does do a surprisingly good job. I write a tools column for the IEEE/PCS (http://ewh.ieee.org/soc/pcs/) and, in November, 2006, wrote a column on that topic. I won’t repeat the details here, but I’ll be happy to send a copy of the column if you’re interested. If so, contact me at nperlin@nperlin.cnc.net.
Visual help authoring tools like Captivate, Camtasia, and Mimic were initially designed for creating software-related “movies” showing how to use features or perform tasks in a piece of software. They’re great tools – easy to use, cheap enough (most in the $299 to $699 range) that they pose a real threat to “big” tools like Authorware and Toolbook, and flexible. That flexibility is one of the best features because it leads authors to use these tools in ways that the vendors perhaps never intended, or even thought of. For example:
Role-playing simulations – The tools make it easy to create role-playing sims like sales or HR training. Captivate 2 came with a sample that tested your skills as an automobile sales rep, and Captivate 3 comes with one that teaches interviewing skills. But these sims can cover almost any topic; in 2007, I created a sim that showed how to determine whether a baby’s diaper needed to be changed. (With apologies to my grand-niece Eleanor Ruby, aka Ellie Belly.)
Games – Your first response to the idea of using these tools to create games may be no. That was mine, until I realized that it simply depends on how you define “game”. In some ways, interactive role-playing or software sims are games – the difference lies largely in the tone. And these tools make it easy to create scorable “games.”
Comics – In early ‘07, an attendee in my Captivate class asked what I thought of the idea of using the tool to create anime-style comics. I was going to say that it didn’t seem appropriate until I remembered the evolution of my thoughts about using Captivate to create games. Depending on what you want to do, I see no reason why not to use these tools to create anime, or other types of comics.
One serendipitous thought about where to get graphics for your animated comics. Silke Fleischer, Adobe’s product manager for Captivate, mentioned in her blog (http://blogs.adobe.com/silke.fleischer/) the idea of creating a Second Life (http://secondlife.com/) account and capturing the characters. This may be a lot of work initially if you can’t find someone who’s already using Second Life, but once you learn the software and create character(s), you effectively have your own animation studio.
Usability test recording – Less odd but more useful, these tools let you create your own usability test recording tools. One of the problems that I often hear regarding usability testing is the cost of the testing facility in general and tools in particular. In response to one question, I figured out how to use Captivate as a tool to record the results of software usability tests. It’s not perfect, but it does do a surprisingly good job. I write a tools column for the IEEE/PCS (http://ewh.ieee.org/soc/pcs/) and, in November, 2006, wrote a column on that topic. I won’t repeat the details here, but I’ll be happy to send a copy of the column if you’re interested. If so, contact me at nperlin@nperlin.cnc.net.
Wednesday, March 26, 2008
iSommelier - Extreme Single Sourcing
There's a lot of talk in technical communication about single sourcing, to put it mildly, but how does single sourcing actually manifest itself?
If we focus on online outputs, we're typically talking about one help file designed for use on a large-screen device like a desktop or laptop PC. Occasionally, someone will output in multiple formats, such as WebHelp and HTML Help, but still for a desktop or laptop PC. Rarely, someone might have to output for handhelds or, rarer still, to voice, ink, or other unusual systems.
One common denominator behind all of these outputs is individual interactions and standard units of content - one person at a time using one topic at a time. But a recent article in Business Week (The iSommelier Will Take Your Order, Feb. 25, 2008, page 72) introduced a new and unusual type of output.
iSommelier is a wine bar with a touch-sensitive surface, like an iPhone and on the same lines as Microsoft's Surface (see http://www.microsoft.com/surface/). The idea behind iSommelier is that guests can review a restaurant's wine selections, read tasting notes, and place orders using their fingers as navigation tools on the device's surface. As the writer describes it:
"... a list of countries materializes. I choose Spain. Then a menu of regions appears, and beneath that, a selection of wines. I drill down some more, and a graphic displays details about the producer and grapes, along with tasting notes arranged in a rosette pattern..."
Touch-screen computers aren't new. ATMs have been around for years. But interfaces like iSommelier offer more interesting displays and group interactivity. It's also an excellent illustration of how unexpected technical and marketing forces may affect how we create and structure content for display in unexpected venues. Imagine that you're the content developer for a wine reference web site and are told by the sales manager that the company just won a bid to provide information for some weird new product called iSommelier... Some possible effects:
- In order to avoid writing content multiple times, you'll have to be able to repurpose your existing content for iSommelier and whatever comes after that.
- The need to manipulate the content means it'll have to be coded using proper syntax. This could drive your move toward XML, since you'll need clean code in order to be able to repurpose the content quickly and automatically.
- The need to manipulate the content also means it must be structured consistently. The obvious answer is structured authoring, but according to what standard? DITA is often presented as the answer to all structured authoring needs but, from what I've seen of it, it lacks the flexibility to handle something this unusual. (I'm open to correction from other DITA users here...)
One argument against worrying about products like iSommelier or technologies like touch-surface driven interfaces is scarcity and price. iSommelier costs $250,000 and Microsoft's Surface is expected to cost $5,000 to $10,000 per unit, limiting their market penetration. True, but notice that Surface is already over 95% cheaper than iSommelier and costs will continue to fall if there proves to be a market for this kind of technology. (The first laser printer I ever saw was the size of a desk and cost about $250,000. My latest is a color laser with automatic two-sided printing that cost $399.)
Without trying to read too much into one interesting but niche product, iSommelier is a harbinger of the types of uses for our content that may show up out of the blue, and that we can only be prepared for by following standards.
There's a lot of talk in technical communication about single sourcing, to put it mildly, but how does single sourcing actually manifest itself?
If we focus on online outputs, we're typically talking about one help file designed for use on a large-screen device like a desktop or laptop PC. Occasionally, someone will output in multiple formats, such as WebHelp and HTML Help, but still for a desktop or laptop PC. Rarely, someone might have to output for handhelds or, rarer still, to voice, ink, or other unusual systems.
One common denominator behind all of these outputs is individual interactions and standard units of content - one person at a time using one topic at a time. But a recent article in Business Week (The iSommelier Will Take Your Order, Feb. 25, 2008, page 72) introduced a new and unusual type of output.
iSommelier is a wine bar with a touch-sensitive surface, like an iPhone and on the same lines as Microsoft's Surface (see http://www.microsoft.com/surface/). The idea behind iSommelier is that guests can review a restaurant's wine selections, read tasting notes, and place orders using their fingers as navigation tools on the device's surface. As the writer describes it:
"... a list of countries materializes. I choose Spain. Then a menu of regions appears, and beneath that, a selection of wines. I drill down some more, and a graphic displays details about the producer and grapes, along with tasting notes arranged in a rosette pattern..."
Touch-screen computers aren't new. ATMs have been around for years. But interfaces like iSommelier offer more interesting displays and group interactivity. It's also an excellent illustration of how unexpected technical and marketing forces may affect how we create and structure content for display in unexpected venues. Imagine that you're the content developer for a wine reference web site and are told by the sales manager that the company just won a bid to provide information for some weird new product called iSommelier... Some possible effects:
- In order to avoid writing content multiple times, you'll have to be able to repurpose your existing content for iSommelier and whatever comes after that.
- The need to manipulate the content means it'll have to be coded using proper syntax. This could drive your move toward XML, since you'll need clean code in order to be able to repurpose the content quickly and automatically.
- The need to manipulate the content also means it must be structured consistently. The obvious answer is structured authoring, but according to what standard? DITA is often presented as the answer to all structured authoring needs but, from what I've seen of it, it lacks the flexibility to handle something this unusual. (I'm open to correction from other DITA users here...)
One argument against worrying about products like iSommelier or technologies like touch-surface driven interfaces is scarcity and price. iSommelier costs $250,000 and Microsoft's Surface is expected to cost $5,000 to $10,000 per unit, limiting their market penetration. True, but notice that Surface is already over 95% cheaper than iSommelier and costs will continue to fall if there proves to be a market for this kind of technology. (The first laser printer I ever saw was the size of a desk and cost about $250,000. My latest is a color laser with automatic two-sided printing that cost $399.)
Without trying to read too much into one interesting but niche product, iSommelier is a harbinger of the types of uses for our content that may show up out of the blue, and that we can only be prepared for by following standards.
Monday, March 10, 2008
Return of RoboSource?
If you used RoboHelp in the X5 days, you may have noticed RoboSource Control - the free version control system that shipped with RoboHelp. It was so simple that many people who saw it had the same initial reaction - "a toy version control system." But that reaction was wrong. RoboSource made version control simple enough that it didn't take your focus away from the actual project work.
Unfortunately, RoboSource 1 had problems. One bug corrupted a RoboHelp project if you added it to version control through RoboSource, but you could add the same project to version control just fine through RoboHelp. There was also a limit to how many files RoboSource could handle. A rule of thumb was to expect problems if a project neared the 2,000 file mark and to be surprised if you didn't get problems above 2,000 files. (2,000 seems like a lot, but consider a 1,000 topic project plus screen shots and you'll see that files add up quickly.) Finally, the documentation wasn't clear, so many people never tried it because they didn't understand how it worked in the first place. And RoboSource just dropped out of sight during RoboHelp's time in limbo under MacroMedia.
When Adobe released RoboHelp 6, one feature that was lost in the uproar was a new version 3 of RoboSource. (Adobe kept RoboSource 3 when it released RoboHelp 7.) I ignored it until three client calls in the space of a month made me go back and look at it again. And helping one client implement it exposed me to some of the internals of the new version and some of its peculiarities.
At a high level, RoboSource 3 works the same way as v. 1. Create the RoboHelp project, then add it to version control. Once you do, there's one other step that has to be performed once. The first time you open a project after adding it to version control, you do so by opening it specifically from the version control system. This creates a local copy of the project on your C drive. From then on, you open the project locally, like you would if the project wasn't in version control. When you do, RoboSource compares the versions of each file in the version control system on the server to the corresponding file on your C drive. If the local version is newer, RoboHelp uses that version. If the server version is newer, RoboSource copies it to the C drive and opens it in RoboHelp. In other words, you're always working on the local version which is being kept up-to-date by RoboSource.
Once the project is in version control, you get the expected check-in and check-out features, along with rollbacks and "diffing" - e.g. "differencing" or comparison of two versions of the same file.
RoboSource 3 still has peculiarities, the biggest apparently still being its file capacity. According to tech support, RoboSource 3 is based on SQL Express so, in theory, its capacity should essentially be unlimited. In practice, however, a client in Florida tried to load a 4,000 topic RoboHelp project (closer to 5,000 files when you count the graphics and control files) only to have RoboSource hang, apparently. This happened late enough in the afternoon that he decided to go home and clean off the server in the morning. But when he arrived the next morning, he found that the project had been added to version control. RoboSource had just gotten tied up with some function the previous afternoon and didn't provide any status messages to that effect, so we thought it had crashed.
In summary, RoboSource 3 is worth a look if you need a cheap and simple version control system. (Do not use the original version, even though it's still available in the RoboHelp 7 toolbox pod.) Try a few small and simple test projects first to see if it's working correctly and, if it is, give it a shot. And let me know what happens...
If you used RoboHelp in the X5 days, you may have noticed RoboSource Control - the free version control system that shipped with RoboHelp. It was so simple that many people who saw it had the same initial reaction - "a toy version control system." But that reaction was wrong. RoboSource made version control simple enough that it didn't take your focus away from the actual project work.
Unfortunately, RoboSource 1 had problems. One bug corrupted a RoboHelp project if you added it to version control through RoboSource, but you could add the same project to version control just fine through RoboHelp. There was also a limit to how many files RoboSource could handle. A rule of thumb was to expect problems if a project neared the 2,000 file mark and to be surprised if you didn't get problems above 2,000 files. (2,000 seems like a lot, but consider a 1,000 topic project plus screen shots and you'll see that files add up quickly.) Finally, the documentation wasn't clear, so many people never tried it because they didn't understand how it worked in the first place. And RoboSource just dropped out of sight during RoboHelp's time in limbo under MacroMedia.
When Adobe released RoboHelp 6, one feature that was lost in the uproar was a new version 3 of RoboSource. (Adobe kept RoboSource 3 when it released RoboHelp 7.) I ignored it until three client calls in the space of a month made me go back and look at it again. And helping one client implement it exposed me to some of the internals of the new version and some of its peculiarities.
At a high level, RoboSource 3 works the same way as v. 1. Create the RoboHelp project, then add it to version control. Once you do, there's one other step that has to be performed once. The first time you open a project after adding it to version control, you do so by opening it specifically from the version control system. This creates a local copy of the project on your C drive. From then on, you open the project locally, like you would if the project wasn't in version control. When you do, RoboSource compares the versions of each file in the version control system on the server to the corresponding file on your C drive. If the local version is newer, RoboHelp uses that version. If the server version is newer, RoboSource copies it to the C drive and opens it in RoboHelp. In other words, you're always working on the local version which is being kept up-to-date by RoboSource.
Once the project is in version control, you get the expected check-in and check-out features, along with rollbacks and "diffing" - e.g. "differencing" or comparison of two versions of the same file.
RoboSource 3 still has peculiarities, the biggest apparently still being its file capacity. According to tech support, RoboSource 3 is based on SQL Express so, in theory, its capacity should essentially be unlimited. In practice, however, a client in Florida tried to load a 4,000 topic RoboHelp project (closer to 5,000 files when you count the graphics and control files) only to have RoboSource hang, apparently. This happened late enough in the afternoon that he decided to go home and clean off the server in the morning. But when he arrived the next morning, he found that the project had been added to version control. RoboSource had just gotten tied up with some function the previous afternoon and didn't provide any status messages to that effect, so we thought it had crashed.
In summary, RoboSource 3 is worth a look if you need a cheap and simple version control system. (Do not use the original version, even though it's still available in the RoboHelp 7 toolbox pod.) Try a few small and simple test projects first to see if it's working correctly and, if it is, give it a shot. And let me know what happens...
Friday, February 29, 2008
MadCap Analyzer
My apologies for commiting the cardinal blogging sin of not posting, but four major projects hit me simultaneously in October and something had to give. Three of those projects are now history and the fourth is almost done, so I can start blogging again...
MadCap Flare is a powerful and feature-packed product, but it's long been deficient in the area of project reporting - the ability to report on such things as the styles used in the project, topics that have not been listed in the index, and so on.
MadCap recently corrected this deficiency with its release of Analyzer. Analyzer is a surprisingly powerful utility that can parse a project and then create reports listing the results, and even suggest improvements to the project.
Analyzer analyzes your project (sorry...) and provides a summary of various issues like the number of topics that have not been added to the table of contents or index, the number of styles in the CSS that have not yet been used (suggesting that they might not be needed in the CSS at all), and so on. Double-clicking an entry in this summary opens a separate window that presents more details about that issue and lets you correct the issue in Analyzer or in Flare (or the forthcoming Blaze).
Analyzer provides a lot of useful information about a project and can be considered the Flare (and Blaze) equivalent of RoboHelp's Reports feature (on the RoboHelp Tools menu). More specifically, Analyzer lets you look at TofC and index entries, variables, snippets, styles, and more. It also flags developer errors, such as undefined styles, variables, glossary entries, and other features that are easy to accidentally leave unfinished. A nice touch is the Replace Local Style Suggestions feature, which flags places in the project where you used local formatting and suggests replacements from the CSS.
Like any other v.1 software, Analyzer has some problems. I ran it on a mid-sized (~700 topic) Flare project and found one apparent problem and one surprising omission:
The problem is the length of time Analyzer took to do the initial analysis of the Flare project, which it has to do before any other Analyzer functions can kick in. It took about five minutes to analyze my topic project. Without any baseline, I can't say whether this is slow, fast, or normal, but it seemed slow.
The omission is the inability to create a simple list of topics in the project. This is a very useful feature, at which RoboHelp excels, because it makes it easy to create project task checklists. For example, let's say you imported an old WinHelp project into Flare and need to look for and fix the style class on the popups. How do you keep track of which topics you've checked? You can just open Flare's File List, which lists the topics alphabetically, and work your way down the list, as long as you don't need to make marginal notes about some topics. A printed, alphabetic list of the topics is a lot more useful. Surprisingly, there's no way to do that in Analyzer *through the interface* or in Flare itself.
There is one way around this omission. It's not perfect, but it's better than nothing. Thanks to Ryan in tech support for suggesting this trick...
One of the reports that Analyzer offers is "Topics Not In Any TOC." So the trick is to temporarily remove all TOCs from the project, which means that, technically, none of the topics are in a TOC and will thus appear on this report. You then generate and print the report, then put the TOCs back into the project. To do this:
1. In Windows Explorer, open the ...Project/TOCs folder under the project folder and change the name of each TOC from.fltoc to .oldfltoc or something like that. The name change makes Flare "lose" the TOCs, which thus means that none of the topics are in a TOC. (Open the TOCs folder on the Project Organizer tab and you'll see that all your TOCs are gone.)
The flaw in this trick is that it is a work-around that requires you to go behind the interface in Flare. But it does work. The drawback is the fact that this trick can't generate an alphabetic list of all the topics in the project. Instead, it generates an alphabetic list of all the topics as they're listed in each folder and sub-folder on the Content Explorer tab in Flare. This means that you can't just scan down the list to find a topic, but instead have to know what folder to look in in the first place. It's not that difficult if you know your project, but it is inefficient.
In summary, Analyzer is fairly inexpensive - regularly $299 but currently available at the promotional price of $199, at a discount for Flare maintenance customers, and free for MadPak maintenance customers. It offers a level of project analysis and reporting that's been sorely missing in Flare, and I recommend it highly.
My apologies for commiting the cardinal blogging sin of not posting, but four major projects hit me simultaneously in October and something had to give. Three of those projects are now history and the fourth is almost done, so I can start blogging again...
MadCap Flare is a powerful and feature-packed product, but it's long been deficient in the area of project reporting - the ability to report on such things as the styles used in the project, topics that have not been listed in the index, and so on.
MadCap recently corrected this deficiency with its release of Analyzer. Analyzer is a surprisingly powerful utility that can parse a project and then create reports listing the results, and even suggest improvements to the project.
Analyzer analyzes your project (sorry...) and provides a summary of various issues like the number of topics that have not been added to the table of contents or index, the number of styles in the CSS that have not yet been used (suggesting that they might not be needed in the CSS at all), and so on. Double-clicking an entry in this summary opens a separate window that presents more details about that issue and lets you correct the issue in Analyzer or in Flare (or the forthcoming Blaze).
Analyzer provides a lot of useful information about a project and can be considered the Flare (and Blaze) equivalent of RoboHelp's Reports feature (on the RoboHelp Tools menu). More specifically, Analyzer lets you look at TofC and index entries, variables, snippets, styles, and more. It also flags developer errors, such as undefined styles, variables, glossary entries, and other features that are easy to accidentally leave unfinished. A nice touch is the Replace Local Style Suggestions feature, which flags places in the project where you used local formatting and suggests replacements from the CSS.
Like any other v.1 software, Analyzer has some problems. I ran it on a mid-sized (~700 topic) Flare project and found one apparent problem and one surprising omission:
The problem is the length of time Analyzer took to do the initial analysis of the Flare project, which it has to do before any other Analyzer functions can kick in. It took about five minutes to analyze my topic project. Without any baseline, I can't say whether this is slow, fast, or normal, but it seemed slow.
The omission is the inability to create a simple list of topics in the project. This is a very useful feature, at which RoboHelp excels, because it makes it easy to create project task checklists. For example, let's say you imported an old WinHelp project into Flare and need to look for and fix the style class on the popups. How do you keep track of which topics you've checked? You can just open Flare's File List, which lists the topics alphabetically, and work your way down the list, as long as you don't need to make marginal notes about some topics. A printed, alphabetic list of the topics is a lot more useful. Surprisingly, there's no way to do that in Analyzer *through the interface* or in Flare itself.
There is one way around this omission. It's not perfect, but it's better than nothing. Thanks to Ryan in tech support for suggesting this trick...
One of the reports that Analyzer offers is "Topics Not In Any TOC." So the trick is to temporarily remove all TOCs from the project, which means that, technically, none of the topics are in a TOC and will thus appear on this report. You then generate and print the report, then put the TOCs back into the project. To do this:
1. In Windows Explorer, open the ...Project/TOCs folder under the project folder and change the name of each TOC from
2. Go to Analyzer and run the Topics Not In Any TOC report.
3. Change the names of the TOCs back to the original fltoc extension.
4. Close the project in Flare, then re-open it, to restore the listing of your TOCs in the TOCs folder on the Project Organizer tab.The flaw in this trick is that it is a work-around that requires you to go behind the interface in Flare. But it does work. The drawback is the fact that this trick can't generate an alphabetic list of all the topics in the project. Instead, it generates an alphabetic list of all the topics as they're listed in each folder and sub-folder on the Content Explorer tab in Flare. This means that you can't just scan down the list to find a topic, but instead have to know what folder to look in in the first place. It's not that difficult if you know your project, but it is inefficient.
In summary, Analyzer is fairly inexpensive - regularly $299 but currently available at the promotional price of $199, at a discount for Flare maintenance customers, and free for MadPak maintenance customers. It offers a level of project analysis and reporting that's been sorely missing in Flare, and I recommend it highly.
Subscribe to:
Posts (Atom)