About That Issue of Tech Writers and Business
I've heard from two people, so far, who read something other than what I intended into what I wrote about tech writers and business, so...
I don't assume that tech writers are incompetent or incapable of understanding business issues. Nor do I hold tech writers who come from fine arts or English backgrounds in disdain. (I have a bachelors in English myself.)
I simply believe that too many tech writers just don't want to get involved in the finance side of business, an attitude that holds those writers back from having a more influential role in their companies' operations. If tech writers are going to compete with consultants and outsourcing and offshoring firms, we need to be able to hold our own in business terms during operational discussions. That's it...
Monday, July 27, 2009
Why Tech Writers Need To Understand Business - Yet Another Example...
For some years, people, myself included, have noted the lack of interest, even disdain, that many tech writers have for business issues. This reduces these writers' ability to affect company decisions, including decisions that may affect them.
One area in which this problem manifests itself is finance. Writers from fine arts or English backgrounds can rarely discuss cost-justification in finance terms, so they have little input on buying decisions. Consider the decision to buy a $100K+ CMS. Spending that much money may require formal cost-justification. If the doc group can't provide it, then either the CMS won't get bought or will get bought but under the control of another department that may or may not take the doc group's needs into consideration.
But there are other areas in which ignorance of business can hurt. One, security, was the subject of an article in a recent issue of Business Week (July 27, 2009, "Google's Battle for the Office"). Here's a quick backgrounder...
Google appears to be attacking Microsoft by undercutting Windows and Office. Google's Chrome browser will let users run applications, like word processors, that reside on a server rather than on users' desktops. And Google's application suite, Google Apps, is intended to compete with Office but with the applications also on a server rather than users' desktops. Undercutting Windows and Office would reduce Microsoft's revenue stream and thus weaken Microsoft.
Love or hate Microsoft, there is some benefit to Google's approach and Google is pushing it. The problem, as the Business Week article noted, is security. Google Apps stores files, like word processing documents and spreadsheets, on Google servers rather than on the client companies' own servers. This means the client companies give up control of their proprietary material. Quote Business Week - " For some companies, the arrangement violates security and accounting policies."
Business trumps technology...
For some years, people, myself included, have noted the lack of interest, even disdain, that many tech writers have for business issues. This reduces these writers' ability to affect company decisions, including decisions that may affect them.
One area in which this problem manifests itself is finance. Writers from fine arts or English backgrounds can rarely discuss cost-justification in finance terms, so they have little input on buying decisions. Consider the decision to buy a $100K+ CMS. Spending that much money may require formal cost-justification. If the doc group can't provide it, then either the CMS won't get bought or will get bought but under the control of another department that may or may not take the doc group's needs into consideration.
But there are other areas in which ignorance of business can hurt. One, security, was the subject of an article in a recent issue of Business Week (July 27, 2009, "Google's Battle for the Office"). Here's a quick backgrounder...
Google appears to be attacking Microsoft by undercutting Windows and Office. Google's Chrome browser will let users run applications, like word processors, that reside on a server rather than on users' desktops. And Google's application suite, Google Apps, is intended to compete with Office but with the applications also on a server rather than users' desktops. Undercutting Windows and Office would reduce Microsoft's revenue stream and thus weaken Microsoft.
Love or hate Microsoft, there is some benefit to Google's approach and Google is pushing it. The problem, as the Business Week article noted, is security. Google Apps stores files, like word processing documents and spreadsheets, on Google servers rather than on the client companies' own servers. This means the client companies give up control of their proprietary material. Quote Business Week - " For some companies, the arrangement violates security and accounting policies."
Business trumps technology...
Monday, July 13, 2009
Questions from the July 7-10 Remote Flare 5.2 Course
Re looking for the definition of "inline marker" as an impromptu test of the help's usability... I found it in under a minute by opening the help Search pane, searching for "inline", clicking "inline markers" in the auto-complete panel, opening the first topic - "Frame Contents Window Pane," and scrolling down until I found the two words highlighted. Here's the definition, from the v. 5.2 help...
"...markers for all inline elements in the active topic. You might find this feature useful if you have imported DITA file content. The reason for this is that DITA inline tags are often for semantic purposes, rather than for changing the look of content. By enabling the inline markers feature, it is easy to tell when particular content is using a tag."
The problem here is the need to scroll almost halfway down the topic to find the definition. However, the highlighting helps. So I'd call this pretty usable...
Re looking for the definition of "inline marker" as an impromptu test of the help's usability... I found it in under a minute by opening the help Search pane, searching for "inline", clicking "inline markers" in the auto-complete panel, opening the first topic - "Frame Contents Window Pane," and scrolling down until I found the two words highlighted. Here's the definition, from the v. 5.2 help...
"...markers for all inline elements in the active topic. You might find this feature useful if you have imported DITA file content. The reason for this is that DITA inline tags are often for semantic purposes, rather than for changing the look of content. By enabling the inline markers feature, it is easy to tell when particular content is using a tag."
The problem here is the need to scroll almost halfway down the topic to find the definition. However, the highlighting helps. So I'd call this pretty usable...
Monday, December 15, 2008
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
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
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...
Subscribe to:
Posts (Atom)