Palimpsest

Congratulations to contest winners...

2009-07-01T13:27:00.003-04:00

...Bjørn Smalbro and Dave Truman, who will receive printed copies of Technical Writing 101.

Thanks to everyone who entered the drawing. Even if you didn't win, you should have received an email with a coupon code for $5 off the PDF download of the book. (If you indicated that you teach technical writing, you should have received a code for a free review copy.)

Keith Soltys posted a review of Technical Writing 101 on his Core Dump blog yesterday. I'm pleased to report the review is positive.

A special alert to my fellow bargain hunters out there: Amazon.com is selling Technical Writing 101 at a steep discount. At the time I posted this blog entry, Amazon is offering the book for $23.73 (34 percent off the $35.95 cover price). The price does fluctuate, so who knows how long that discount will be in effect.

This is the future of technical communication

2009-06-29T10:39:00.001-04:00

First, read this article in the New York Times about the struggle to keep a reporter's kidnapping quiet:

For seven months, The New York Times managed to keep out of the news the fact that one of its reporters, David Rohde, had been kidnapped by the Taliban. But that was pretty straightforward compared with keeping it off Wikipedia.

Now, think about these issues as applied to technical communication. Let's assume that your organization has online community -- forums and a wiki, maybe. Technical communicators are responsible for monitoring and managing the community. Under what circumstances do you delete information? How do you respond when:

Information is inaccurate
Information is unflattering
Both

What if the information is accurate but incomplete?
What if someone describes a way of using your product that could cause injury, even though it's technically possible? Do you delete the information? Do you add a comment warning of possible injury? What if the reader sees the original post but not the comment?

In the absence of safety concerns, I think that accuracy must win. Thus, as the information curator, you have a responsibility to correct inaccurate information. If the inaccuracy is truly dangerous, you may need to edit the post directly. Make sure that you disclosure what you've done with brackets. For example:

I like riding my scooter down mountains, especially without guardrails. Wheee! [This is a really bad idea because You Might Die. -moderator]

or

I like [really bad idea redacted by moderator]. Wheee!

Deleting unflattering (but accurate) information will probably backfire on the organization. Instead of censoring negative content, try addressing the concern being identified. Think of an impolite forum post as customer feedback. Does the poster have a valid point? Can you fix the problem that's been identified?

I hate your scooters. They don't come in enough colors. And they suck.

What colors would you like to see? We do have two dozen available, see this list.
- Joe in TechComm

The life-or-death issues around Mr. Rohde's kidnapping are relatively straightforward. We are likely to have much more difficult judgment calls in typical technical communication. Imagine, for example, that information were being suppressed because it criticized security arrangements and not because of safety concerns for the reporter. In that case, I think we can agree that Wikipedia's response would have (and should have) been different. What would an equivalent scenario look like in your organization?

Enter soon: Technical Writing 101 contest ends tomorrow

2009-06-29T08:05:00.005-04:00

We're giving away two printed copies of Technical Writing 101 (third edition) on Wednesday. Please enter the drawing before it closes tomorrow.

We're giving away the books to celebrate the book's wider release to online bookstores such as Amazon.com, Amazon.co.uk, Amazon.de, Amazon.fr, and BN.com; you can also place a special order for Technical Writing 101 at your local bookstore. If you want instant access to the book, you can download the PDF version for $20 from our online store.

We achieved this wider distribution by working with another print on demand (POD) company, Lightning Source. We're quite happy with the quality of the books from our other POD partner, Lulu.com. However, at this time, Lulu doesn't offer distribution for publishers who use their own International Standard Book Numbers (ISBNs). We've released books under our own ISBNs since we published the first edition of Technical Writing 101 in 2000, and I frankly was not comfortable assigning an ISBN owned by a POD firm to content we developed. Using a publisher's ISBN would cause problems if we wanted to switch to another publisher later. We'd have to assign a new ISBN, and then the book would be in the marketplace with two different ISBNs. I wanted to prevent that marketing (and distribution) headache from ever happening.

I'm not going to write a long post about the virtues of Lulu.com and other POD publishers vs. Lightning Source because many other people have done that (in this blog post, for example). What I will say, though, is that Lightning Source is geared more toward experienced publishers, and Lulu provides more guidance that newer authors and publishers will certainly appreciate. If you want to get your feet wet in the POD pool, Lulu is a great place to start, but if you're a publisher who has published several titles with your own ISBNs, Lightning Source may be better suited for your needs.

Win a printed copy of Technical Writing 101 (third edition)

2009-06-24T10:01:00.007-04:00

As of this week, the printed version of Technical Writing 101 (ISBN 9780970473363) is available at online bookstores, and you can also special order a copy from your local bookstore. To celebrate the book's wider distribution, we're giving away two printed copies.

Enter the contest by June 30 (next Tuesday). We'll pick two winners at random on July 1.

The printed book is now listed at many online stores, including Amazon.com, Amazon.co.uk, Amazon.de, Amazon.fr, and BN.com. (FYI to all you bargain hunters out there: some of these stores are selling the book at a discount and with free shipping, too.)

For those of you who want instant (and cheaper) access to the book, we're still offering the PDF download (ISBN 9780970473370) for $20. The download (which has been particularly popular with buyers outside the US) is available only through our online store.

Later, I'll write more about how we achieved the wider distribution of the printed version through our new print-on-demand partner, Lightning Source, and how Lightning Source compares to Lulu.com.

Automated trademarking in structured documents – DITA in particular

2009-06-22T13:21:00.005-04:00

Unabashed plug warning: The following entry gives a conceptual overview of a solution Scriptorium has implemented for managing trademarks in structured tagging. And we're proud of it.

You know the problem. According to your style standards, only the first instance of a given trademarked term should display the trademark symbol. Structured documentation allows you to re-use document parts (such as DITA topics) in just about any order you like. In Manual A, the first file containing the trademarked text is, say, Topic A; in Manual B the first file containing the trademarked text is Topic E, which is also used in Manual A. Where do you put your trademark markup, and how do you maintain it when running Manual A and Manual B at approximately the same time?

Maintaining the trademarks by hand adds a level of effort that becomes non-negligible when you start considering a large number of manuals. And the process becomes error prone – those darned human beings. Different writers might tag things different ways, trademarks might escape notice, or markup might be inserted in inappropriate places by accident.

Isn't this one of those problems that automated documentation was supposed to solve, not create? I once had a professor who said that computers were supposed to handle the work that computers could solve so people could work on the problems that only people can solve.

More than one of Scriptorium's customers has presented us with this problem, so we know it is not uncommon. We have found a way to deal with the problem in DITA, and we believe that the principle is sufficiently generic to use in non-DITA structures as well.

To begin with, forget conditional processing. It won't help you with the problem of marking only the first instance of a term. In the example of Manual A, above, setting the condition “Manual A” would still display the trademark in Topic A and Topic E. This is not what your editor wants – and he or she will let you know it in spades if he or she is any kind of editor at all.

Scriptorium's solution for DITA, in simple outline, is as follows:

Using XSL, go through the ditamaps and remove all trademarking from the document files.
Following a predefined list of trademarked and registered trademarked terms, go through the ditamaps and identify the files that contain each term. Create a temporary file that lists the relevant files in order of book occurrence. (This step prevents having to crawl through the ditamaps more than once.)
Using Perl, iterate through the files listed for each term in the temporary file. Check the occurrence of each instance of the term, in text order, and evaluate whether it is a valid occurrence that requires trademarking. If so, wrap the appropriate trademark markup around it and go to the next trademark. If not, keep going through the text and the list of files until you find a valid occurrence of this trademark.

We possibly could have used XSL instead of Perl for the third step, but Perl's text manipulation capability is much more robust than XSL's, so we chose Perl.

In the implementation, the trademarking utility is coordinated by an Ant process. A user runs this utility just before the book is rendered for output. Being in Ant, the trademarking process could probably be integrated into the DITA Open Toolkit build system fairly easily to create a seamless, one-step production process.

There are a number of interesting problems that arise during implementation. For example, in step 3 the process has to evaluate whether the instance of a term is valid for trademarking. Some kinds of non-valid instances of a term in the text might be:

The term is in an indexterm tag.
The term is in an href attribute.
The term is in a title.
The term is in a codeblock tag.

You might also encounter a condition where a trademarked term could be both mixed case and all uppercase. Per your style guide, only the first instance of either should be marked, but not the first instance of both. That sort of requirement makes life just a little more interesting for a coder.

In general, the issue of trademarking first instances is not a simple problem to solve, and variations in style requirements will undoubtedly add complexity and challenges to the problem. But that's what automated documentation is supposed to be good at, right? So we humans can get back to doing the more difficult problems that only people can solve.

I'm not sure – is that really such a good deal?

Whither STC?

2009-06-19T16:11:00.002-04:00

As you may have heard, STC is in a financial crisis. According to the board of directors meeting minutes from May 5, 2009 (PDF, page 2), STC must retain membership "for the next year or STC will be out of business in two years." There's a lively discussion on Twitter under the #stcorg hashtag.

For example, Bill Swallow (@techcommdood) wrote: "From STC I want innovation, education, and communication. Right now I get advertising, magazines, and frustration. #stcorg"

STC itself has requested feedback via private email, on Twitter with the #stcorg tag, and on a "private online forum." I appreciate the idea, but I prefer to share my thoughts here, where anyone can read and comment on them.

According to the June 18 email message from Cindy Currie (STC president), the "unprecedented financial shortfall" is being caused by "the recession's negative impact on our traditional sources of revenue." Although it's certainly true that the recession has caused a decline in membership along with a decline in conference attendance (the biggest two sources of income for STC), the recession is not the root cause of the problem.

The root cause is that STC is not perceived as sufficiently important by its membership. After all, a member could pay $200 for a membership by dropping cable television for a couple of months. Getting rid of cable for a year would come close to paying for conference attendance. It is true, of course, that a few members are in serious financial trouble due to layoffs or reduced income. In most cases, however, I think the member (or the sponsoring employer) has simply decided that STC (or the conference) does not offer enough value to justify the cost.

I have been an STC member for many years, and am an associate fellow. I participate in the annual conference both as a speaker and as an exhibitor. My company is a member of the Corporate Value Program. I have served on a couple of society-level committees and initiatives. This doesn't make me a typical member, but I think it does give me a fairly broad perspective on the organization as a whole.

I believe that STC needs to make some significant changes in the following areas.

Velocity
Industry developments are fast and furious, and STC has not kept pace. For the STC conference, generally held in May, proposals are due the preceding summer. I turned in an article for Intercom on June 16, which will appear in the September issue. Chris Hester (@chris_oh) said it best on twitter: "Why pay for a pub when it uses content that was on blogs months earlier?"

STC needs to increase what the military calls operational tempo. Intercom, as many others have said, probably needs to evolve into an online publication to cut down the publication time. This has some significant advantages:

Faster publishing
Cheaper publishing by eliminating print production, paper, and distribution costs
Ability to publish more often

There is concern that putting Intercom online (and, by the way, I do not mean in PDF format) would put a dent in advertising revenue. It will. However, my company does not currently advertise in Intercom because we think the rates are too high and the value is not there. I would greatly prefer advertising in an online Intercom. I would also expect those rates to be significantly lower than the equivalent print ad. Providing Intercom online would open up advertising to many smaller companies. Would it be more profitable? I don't know, but it would be a better, more relevant, publication, so that's a start.

Similarly, the proposal process for the annual conference needs to be compressed significantly. With nine months of lead time, it's impossible to provide relevant content. And please don't tell me "it can't be done." Joe Welinske of WritersUA usually evaluates proposals in September/October for a March conference. Germany's tekom, which is significantly larger than the STC conference, generally requires proposals in May for a November event. Six months is still a long time, but it's one-third shorter than STC's process.

Community
STC's main value is in providing a sense of community for technical writers/communicators. In the past, the organization delivered community through printed magazines mailed to the membership, through local chapter meetings, and through regional and national conferences. As email lists became popular, STC has provided discussion lists for various SIGs, local chapters, and other groups (for example, there is a chapter presidents' list. Or so I hear).

Today, however, communities of interest are meeting through various social media, and STC has not kept pace. STC should be providing a platform that encourages discussion and collaboration. The obvious template for this is what Scott Abel has done with the Content Wrangler network. STC serves writers; give the writers a place to write blogs, collaborate on a wiki, and the like.

Incidentally, STC Body of Knowledge effort is an excellent example of open collaboration. However, it's quite difficult to find it from the main STC web site. These and other initiatives should all be under the stc.org umbrella. It's not particularly difficult to set up subdomains so that, for example bok.stc.org points to the Body of Knowledge and forum.stc.org points to the forums. And so on.

Openness
Finally, STC needs to embrace a culture of openness. That means:

Provide open access to Intercom and other publications online. Increase the readership, make the publications more relevant, and therefore increase their appeal to advertisers.
Provide open access to forums and other collaboration areas. Do not limit them to members only. The STC Single Sourcing SIG recently launched a Ning network (here), but access is restricted not just to STC members but actually to SIG members only. This balkanization reduces the value of the community. Instead, open up participation and build a valuable, must-have resource.
Improve member communications and especially focus on giving people a way of letting their voices be heard. The virtual town halls now in progress are a good idea, but the process of getting access is too difficult. I finally resorted to begging for help on twitter and got the information I needed in less than five minutes. Unless there is a compelling reason to lock up information, it should be publicly available.

Change is hard. Transformational change is painful.
I have worked with many of the people in the STC office and in STC leadership, and it's important to recognize that they are hard-working, smart people. I like them. (One of them is particularly entertaining in a hotel bar at 1 a.m. You Know Who You Are.)

They see the icebergs ahead and are trying hard to navigate through them. The problem is that turning a cruise ship takes time and effort. And, if you'll pardon the tortured analogy, the larger problem is navigating through the ice field is impossible with a huge cruise ship. The correct answer is to step outside today's constraints and rethink the problem. Perhaps we should morph into a submarine and go under the icebergs. At this point, we are still discussing whether to make a 5-degree or a 10-degree turn.

The financial problem that STC faces is a symptom, not the disease. Let's treat the symptom and get through this crisis, but please do not forget about the underlying disease. STC needs more velocity, more community, and more openness.

Update (6/23/2009): Since I published this post, several other bloggers have added their perspectives. Here they are, in no particular order. If I missed your post, please add it in the comments so that readers of this article can find you.

Lifelines to the STC, Tom Johnson, I'd Rather Be Writing
In Which I Comment on the STC Issue, Keith Anderson, mkanderson.com
Does the STC Deserve to Survive?, David Farbey, The Blockhead Blog
It's STC Not STW, Alan Porter, 4J's Group
The STC Crisis: The take of a "young" writer, Paul Pehrson, Technically Speaking
Bye bye STC, Gordon McLean, one man writes
STC Floundering?, Keith Soltys, Core Dump

Flare 5 DITA feature review, part 2

2009-06-17T14:00:00.000-04:00

[Alan Pringle wrote most of this review.]

This post is Part 2 of our Flare 5 DITA feature review. Part 1 provides an overview and discusses localization and map files.

Cross-references and other links
I imported DITA content that contained three xref elements (I shortened the IDs below for readability):

Reference to another step in the same topic:
<stepresult>
Result of step. And here's a reference to the <xref href="task1.xml#task_8F2F9" type="li" format="dita" scope="local">third step</xref>.
</stepresult>

Reference to another topic:
<stepresult>
Result text. And here's a link to the other task topic:
<xref href="task2.xml#task_8F2F94 type="task" format="dita" scope="local"></xref>.
</stepresult>

Link to web site:
<cmd>
Here's another step. Here's a link with external scope:
<xref href="http://www.scriptorium.com" scope="external" format="html">www.scriptorium.com</xref>
</cmd>

All three came across in the WebHelp I generated from Flare:

On the link to the topic, Flare applied a default cross-reference format that included the word "See" and the quotation marks around the topic's name. You can modify the stylesheet for the Flare project to change that text and styling.

Relationship tables
DITA relationship tables let you avoid the drudgery of manually inserting (and managing!) related topic links. Based on the relationships you specify in the table, related topic links are generated in your output.

I imported a simple map file with a relationship table into Flare and created WebHelp. The output included the links to the related topics. I then tinkered with the project's stylesheet and its language skin for English to change the default appearance and text of the heading for related concepts. The sentence-style capitalization and red text for "Related concepts" in the following screen shot reflect my modifications:

conrefs
DITA conrefs let you reuse chunks of content. I created a simple conref for a note and then imported the map file with one DITA file that contains the actual note and a second file that references the note via a conref.

Flare happily imported the information and turned the conref into a Flare snippet. It's worth noting that the referencing, while equivalent, is not the same. In my source DITA files, I had this:

aardvark.xml contains:
<note id="">Do not feed the animals

baboon.xml contains:
<note conref="aardvark.xml#aardvark/nofeeding">

Thus, we have two instances of the content in the DITA files -- the original content and the content reference. In Flare, we end up with three instances -- the snippet and two references to the snippet. In other words, Flare separates out the content being reused into a snippet and then references the snippet. This isn't necessarily a bad thing, but it's worth noting.

Specialization
Specialized content is not officially supported at this point. According to MadCap, it worked for some people in testing, but not for others. If you need to publish specialized DITA content through Flare, you might consider generalizing back to standard DITA first.

Conditional processing
When you import DITA content that contains attribute values, Flare creates condition tags based on those values. I imported a map file with a topic that used the audience attribute: one paragraph had that attribute set to user, and another had the attribute set to admin. When I looked in the Project Organizer at the conditions for the WebHelp target, conditions based on my audience values were listed:

I set Audience.admin to Exclude and Audience.user to Include, and then I created WebHelp. As expected, the output included the user-level paragraph and excluded the admin-level one.

DITA support level
Flare supports DITA v1.1.

Our verdict

If you're looking for a path to browser-based help for your DITA content, you should consider the new version of Flare. Without a lot of effort, we were able to create WebHelp from imported DITA content. Flare handled DITA constructs (such as conrefs and relationship tables) without any problems in our testing. Our only quibble was with the TOC entries in the WebHelp (as mentioned in Part 1), and we've heard that MadCap will likely be addressing that issue in the future.

We didn't evaluate how Flare handles DITA-to-PDF conversion. However, if the PDF process in Flare works as smoothly as the one for WebHelp, Flare could provide a compelling alternative to modifying the XSL-FO templates that come with the Open Toolkit or adopting one of the commercial FO solutions for rendering PDF output.

Flare 5 DITA feature review (Part 1: Overview and map files)

2009-06-12T10:05:00.001-04:00

[Disclosure: Scriptorium is a Certified Flare Instructor.]
[Full disclosure: We're also an Adobe Authorized Training Center, a JustSystems Services Partner, a founding member of TechComm Alliance, a North Carolina corporation, and a woman-owned business. Dog people outnumber cat people in our office. Can I start my post now?]

These days, most of our work uses XML and/or DITA as foundational technologies. As a result, our interest in help authoring tools such as Flare and RoboHelp has been muted. However, with the release of Flare 5, MadCap has added support for DITA. This review looks at the DITA features in the new product. (If you're looking for a discussion of all the new features, I suggest you wander over to Paul Pehrson's review. You might also read the official MadCap press release.)

The initial coverage reminds me a bit of this:

(My web site stats prove that you people are suckers for video. Also, I highly recommend TubeChop for extracting a portion of a YouTube video.)

Let's take a look at the most important Flare/DITA integration pieces.

New output possibilities
After importing DITA content into Flare, you can publish to any of the output formats that Flare supports. Most important, in my opinion, is the option to publish cross-browser, cross-platform HTML-based help ("web help") because the DITA Open Toolkit does not provide this output. We have created web help systems by customizing the Open Toolkit output, and that approach does make sense in certain situations, but the option to publish through Flare is appealing for several reasons:

Flare provides a default template for web help output (actually, three of them: WebHelp, WebHelp Plus, and WebHelp AIR)
Customizing Flare output is easier than configuring the Open Toolkit

I took some DITA files, opened them in Flare, made some minimal formatting changes, and published to WebHelp. The result is shown here:

Not bad at all for 10 minutes' work. I added the owl logo and scriptorium.com in the header, changed the default font to sans-serif, and made the heading purple. Tweaking CSS in Flare's visual editor is straightforward, and changes automatically cascade (sorry) across all the project files.

Ease of configuration
Flare wins. Next topic. (Don't believe me? Read the DITA Open Toolkit User Guide -- actually, just skim the table of contents.)

Language support
The Open Toolkit wins on volume and for right-to-left languages; Flare wins on easy configuration (I'm detecting a theme here.)

Out of the box, both Flare and the Open Toolkit provide strings (that is, localized output for interface elements such as the "Table of Contents" label) for simplified and traditional Chinese, Danish, Dutch, English, Finnish, French, German, Italian, Japanese, Korean, Norwegian, Portugese, Spanish, Swedish, and Thai (I have omitted variations such as Canadian French).

Beyond that, we have the following:

Right-to-left language support: Only in the Open Toolkit
Language strings provided by the Open Toolkit but not by Flare: Arabic, Belarusian, Bulgarian, Catalan, Czech, Greek, Estonian, Hebrew, Croatian, Hungarian, Icelandic, Latvian, Lithuanian, Macedonian, Polish, Romanian, Russian, Slovak, Slovenian, Serbian, Turkish, and Ukrainian
Ease of adding support for a new language: Flare wins. In the Open Toolkit, you modify an XML file; in Flare, you use the Language Skin Editor (although it looks as though you could choose to modify the resource file directory directly if you really wanted to)

Thus, if you need Hebrew or Arabic publishing, you can't use Flare. The Open Toolkit also provides default support for more languages.

Map files
I imported a map file into Flare and published. Then, I changed the map file to include a simple nested ditamap. Here is what I found:

Flare recognized the map file and the nested map file and built TOC files in Flare with the correct relationships.
Inexplicably, the nested map file was designated the primary TOC. I speculate that this might be because the nested map file was first in alphabetical order. I changed the parent map file to be the primary TOC to fix this. I don't know what would happen for a more complex set of maps, but I am concerned.
Flare inserted an extra layer into the output TOC where the nested map is found.
The titles generated in the TOC are different in Flare than they are through the DITA Open Toolkit (see below).

I generated the output for my map file (the nested map is the "The decision to implement" section in this screen shot) through the DITA Open Toolkit and got the following XHTML output:
Then, I imported the same map file into Flare, generated WebHelp, and got the following TOC output:

Notice that:

The TOC text is different (!!). The DITA Open Toolkit uses the text of the topic titles from inside the topic files. Flare uses the text of the @navtitle attribute in the map file. My topic titles and @navtitles don't match because I created the map file, then changed a bunch of topic titles. The map file didn't keep up with the new titles (because it doesn't matter in the Open Toolkit), but it appears to matter for Flare. The entry in the map file for the first item is:

<topicref href="introduction.xml" navtitle="Introduction" type="topic">

<title>Executive summary</title>

The Implementation section has added an extra layer in the Flare output. It appears that nesting a map file results in an extra level of hierarchy.

The inconsistency between the two implementations is annoying.

In part 2 of this review (coming soon), I'll look at cross-references, reltables, conrefs, specialization, and conditional processing.

Top five reasons to like XMetal and OXygen

2009-06-11T13:54:00.013-04:00

Full disclosure: We're an XMetaL Services Provider and have no particular affiliation with oXygen.

I'm in the fortunate situation of having access to both XMetaL 5.5 and oXygen 9.3. Both are excellent XML editors for different reasons. I'd hate for Scriptorium to make me choose one over the other.

From the viewpoint of authoring XML and XSLT, here are my top five features of both editors:

oXygen

Apply XSLT on the fly: You can associate an XML file with an XSLT and transform the XML within oXygen. Goodbye, command line! XMetaL will convert the document to a selected output format. You don't choose the XSLT--it hasn't been a big concern for me.
Indented code: The pretty-print option makes working with code so easy. You can set oXygen to do this automatically when you open a file or on demand. The result is code indented according to the structure. XMetaL doesn't have pretty print.
Autocompleting tags: As you type an element, oXygen pops up a list of elements beginning with the typed string. You press Enter when you find the right tag, and the end tag is inserted for you. The valid attributes at any particular point are also shown in a drop-down list. XMetaL doesn't have autocompleting tags.
Find/replace in one or more documents: I've often needed to search and replace strings in an entire directory. In XMetaL, you can only find and replace in the current document.
Comparing two documents or directories: Compare files by content or timestamp. In a directory, you can even filter by type so only XML files, for example, are compared. XMetaL doesn't offer this feature.

XMetaL

Auto-tagging content: You can copy and paste content from an unstructured document (a web page, for example), and XMetaL automatically wraps the content in elements. Even tables and lists are wrapped correctly. This can be handy if you have a few documents to convert. In oXygen, the content is pasted as plain text.
Auto-assignment of ID attributes: Never worry about coming up with unique IDs. XMetaL will assign them to the types of elements you select. Warning: The strings are quite long, as in "topic_BBEC2A36C97A4CADB130784380036FD6." oXygen only inserts IDs on the top-level element but full support will be added in version 10.3.
Auto-insertion of basic elements: When you create a document, XMetaL inserts placeholders for elements such as title, shordesc, body, and p. It's a small convenience. oXygen will also insert elements if you have Content Completion selected in the Preferences.
WYSIWYG view of tables: The table is displayed as you'd see it in a Word or FrameMaker document. In oXygen, all you see are the table element tags.
Reader-friendly tag view: The tags are a bit easier to read in XMetaL than oXygen. In XMetaL, the opening and closing tags are displayed on one line when possible. This feature saves space on the page and makes the document easier to read in tag view. For example, you might have a short sentence wrapped in p tags. In XMetal, the p tags are displayed on the same line. In oXygen, the p tags are always on separate lines. This is another convenience that doesn't sound like a big deal, but it really makes a difference while you're authoring.

oXygen and XMetal have so many other strengths. I've just chosen my top five features.

What I'd like to see in XMetaL: The ability to indent code, the ability to drag and drop topics in the map editor.
What's I'd like to see in oXygen: The ability to view a table--lines and all--in the WYSIWYG view instead of just the element tags.

So how do I choose which editor to use at a particular moment? When I'm casually authoring in XML, I choose XMetaL for all of reasons you read above. The WYSIWYG view is more user-friendly to me. But when I'm writing XSLT or just want to get at the code of an XML document, oXygen is my choice.

Get the scoop on oXygen from http://oxygenxml.com. Read more about XMetaL at http://na.justsystems.com/index.php.

Update 6/15/09:
I'm thrilled to report that two deficiencies I reported in oXygen 9 are now supported in the latest version of oXygen -- 10.2.

In Author view, tables are now displayed in WYSIWYG format. Just like in your favorite word processor, you can drag and drop column rulings to resize columns. After you resize columns, the colwidth attribute in the colspec element is updated automatically. This is much easier than manually editing the colwidth.
In Author view, the tags are now displayed on one line when possible. Before, the tags were always on separate lines from the content.

Two more reasons to love oXygen!

Webinar mania!

2009-06-09T10:08:00.006-04:00

I have several webinar-related updates to share:

Next week, the State of Structure

You probably know that Scriptorium conducted an industry survey on structured authoring earlier this year. The report, The State of Structure in Technical Communication, is available in our online store for $200.

There is a cheaper option to get the highlights. On Tuesday, June 16, at 1 p.m. Eastern time, I'll be delivering a one-hour webinar that highlights the most important findings.

Coming in July and August

Expect to see additional webinars in cooperation with our TechComm Alliance partners, Cherryleaf and HyperWrite. We are also welcoming Jack Molisani of ProSpring, who will offer excellent and candid career development advice. Watch this space for details about these upcoming events. Scriptorium consultants will also be offering additional content.

Recorded events

Two of our recent webinars are now available for download:

Hacking the DITA Open Toolkit
Documentation as Conversation

Each webinar lasts about one hour and is $20, either live or recorded. You can register for the Tuesday webcast and download recordings in our online store.

(Warning: The recorded webcast files are quite large.)

More cowbell!

2009-06-04T08:00:00.000-04:00

About a year ago, we added Google Analytics to our web site. I have done some research to see what posts were the most popular in the past year:

The clear winner was our FrameMaker 9 review. With 21 comments, I think it was also the most heavily commented post. Interestingly, the post itself is little more than a pointer to the PDF file that contains the actual review.
InDesign CS4 = Hannibal post, which discussed InDesign's encroachment on traditional FrameMaker features.
A surprise...a post from 2006 in which Mark Baker discussed the merits (or lack thereof) of DITA in To DITA or not to DITA

Our readers appear to like clever headlines, because I don't think the content quality explains the high numbers for posts such as:

We noticed this pattern recently, when a carefully crafted, meticulously written post was ignored in favor of a throwaway post dashed off in minutes with a catchy title (Death to Recipes!).

For useful, thoughtful advice on blogging, I refer you to Tom Johnson and Rich Maggiani. I, however, have a new set of blogging recommendations:

Write catchy titles
Have an opinion, preferably an outrageous one
More cowbell

Our first experience with print on demand (POD)

2009-06-03T08:12:00.000-04:00

It's been a little over a month since we released the third edition of Technical Writing 101. The downloadable PDF version is the primary format for the new edition, and we've seen more sales from outside the U.S. because downloads eliminate shipping costs and delays.

Selling Technical Writing 101 as a PDF file has made the book readily available to a wider audience (and at a cheaper price of $20, too). However, we know that a lot of people still like to read printed books, so we wanted to offer printed copies—but without the expense of printing books, storing them, and shipping them out.

We have published several books over the past nine years, and declining revenue from books made it difficult for us to justify spending thousands of dollars to do an offset print run of 1000+ copies of Technical Writing 101 and then pay the added expense of preparing individual books for shipment as they are ordered. Storage has also been a problem: we have only so much space for storing books in our office, and we didn't want to spend money on climate-controlled storage for inventory. (Book bindings would melt and warp without air conditioning during our hot, humid summers here in North Carolina.) For us, the logical solution was print on demand (POD): when a buyer orders the book, a publishing company prints a copy using a digital printing process and then ships it.

We chose Lulu.com for our first experiment with POD, and so far, we have been happy with the quality of the books from there. We are still exploring our options with POD and may try some other companies' services in the future, but based on our experience so far, I can offer two pieces of advice:

Follow the specs and templates provided by the printer, and consider allowing even a bit more wiggle room for interior margins. The first test book I printed had text running too close to the binding, so I made some adjustments to add more room for the interior margins before we sold the book to the public.
Look at the page sizes offered by the different POD publishers before choosing a size. If you choose a page size that multiple POD publishers support, you'll have more flexibility in using another publisher's services in the future, particularly if they offer other services (distribution, etc.) that better suit your needs. Also, ensure the page size you choose is supported when printing occurs in a country other than your own; some publishers have facilities and partners in multiple countries. In an attempt to minimize the amount of production work for the third edition, I chose a page size for Technical Writing 101 that was the closest match to the footprint of the previous edition's layout. However, I likely would have chosen a different page size if I had known more about the common sizes across the various POD companies. The page size I chose at Lulu is not supported by CreateSpace, which is Amazon's POD arm. When you publish through CreateSpace, you get distribution through Amazon.com, which isn't the necessarily the case with other POD publishers. (I've read several blog posts about how some authors use the same sets of files to simultaneously publish books through multiple POD firms to maximize the distribution of their content.)

In these tight economic times, POD publishing makes a lot of sense, particularly when you want to release content in print but don't want to invest a lot of money in printing multiple copies that you have no guarantee of selling. The POD model certainly was a good match for Technical Writing 101, so we decided to give it a try.

I'll keep you updated on our experiences with POD publishing in this blog. If you have experience with POD, please leave a comment about how it's worked for you.

A different take on Twittering and technical writers

2009-06-02T14:02:00.002-04:00

Technical writers abound on Twitter as do blog posts on how Twitter can make you a better tech writer.

I'd Rather Be Writing has an alternate take in the article Following the NBA Can Make You a Better Writer. Tom Johnson uses the analogy of Kobe Bryant and Lebron James playing their respective positions on the court. He argues that unless you're a one-person shop, you're doing yourself a disservice by trying to be a Jack- or Jill-of-all-trades. Play up your strengths, and minimize your weaknesses, tech writers. Read Tom's article for more.

Technical writing and social networks

2009-06-01T10:40:00.003-04:00

There is an interesting thread on techwr-l about using social networking sites to deliver product information. In the thread, Geoff Hart notes there is a generation gap in those who turn to unofficial online resources vs. product documentation:

The young'uns go to the net and social networks more than we older folk, who still rely on developer-provided documentation. We ignore this change at our peril. Cheryl Lockett Zubak had a lovely anecdote at WritersUA a few years ago about how she and her son both set out to solve an iPod problem; they both found the solution in roughly equal amounts of time, but she found it in Apple's documentation, while her son found it on YouTube.

My experience as a user straddles both relying on official docs and information available elsewhere. When my iPod locked up a few years ago, I found decent information on Apple's web site, but the best resource for my particular problem turned out to be on YouTube. A user had made a video showing step-by-step what to do.

The dilemma of official docs vs. Web 2.0 information partially boils down to question of audience. As part of the process for planning and developing content, technical communicators should evaluate and remember the audience, and that audience consideration now needs to extend to how a company distributes the content. I don't think there are cut-and-dried answers here; for example, it's unwise to make the assumption that all folk over a certain age are unaware of or don't use social networks and other Web 2.0 resources. Ignoring unofficial information channels is certainly not the solution, however.

Webcast: Structured authoring survey results

2009-05-27T09:00:00.001-04:00

June 16, ~~11 a.m.~~ 1 p.m. Eastern time

I will be reprising my STC conference presentation, "The State of Structure in Technical Communication." This webcast will discuss some of the results from our industry survey on structured authoring.

If you can't wait that long, the report itself is available in our store.

Register for the webcast

Think global

2009-05-26T09:00:00.003-04:00

We are joining with a couple of other technical communication companies to form the TechComm Alliance:

Three companies—Cherryleaf Ltd., HyperWrite, and Scriptorium Publishing—are forming TechComm Alliance to help us handle technical communication projects around the world. We are located in the United Kingdom, Australia, and the United States, respectively, and each company has customers in both its home location and in other countries. TechComm Alliance will make it easier to work with global companies that need services worldwide.

How will this work? We expect to:

Work together on large projects that require support in multiple locations. For instance, Scriptorium might be implementing structured authoring for a U.S. company that also has operations in Europe and Australia. During rollout, instead of sending a Scriptorium consultant around the world, we partner with Cherryleaf for the training in Europe and with HyperWrite for the training in Australia. The result? Our customer saves on travel expenses, and our consultants spend less time in airplanes.
Refer projects to each other. Each company has (and will continue to have) clients around the world. When we feel that a local presence would benefit the customer, we can refer the project to our alliance partners.
Produce webinars and other events together. I'd like for Scriptorium customers to benefit from the expertise of our partners, and we are working on joint webinars.

Documentation as conversation webinar

2009-05-22T08:38:00.002-04:00

We have added Documentation as Conversation, presented by Anne Gentle, to our upcoming webinars. Anne is scheduled to present on June 9 at 11 a.m. Eastern time:

Even if your documentation system does not converse with your users, your documentation can help customers talk to each other and make the connections that help them do their jobs well or learn something new as if they were in a classroom with a community for classmates. This talk describes how you can think about documentation and user assistance in a conversational way, with the help of social media technology. I'll discuss the topics in my new book, Conversation and Community: The Social Web for Documentation. I'll describe the use of in-person Book Sprints that combine wikis and community events to gather together writers to accomplish documentation goals

Anne is an expert, perhaps the expert, on using wikis and other social media to extend traditional documentation efforts. She's also an excellent speaker, so I hope you'll join us for this session.

Register for Documentation as Conversation ($20)

See all upcoming webinars

PS We are working on additional topics and looking for more speakers. Do you have topics you would like us to cover? Please let us know. We are working on a couple of sessions on document conversion.

This weekend, get $5 off printed copies of Technical Writing 101

2009-05-21T07:26:00.003-04:00

Starting tomorrow through Monday, you can get $5 off a printed copy of Technical Writing 101, which is normally $35.95. To get the discount, use the code MEMORIAL09 during checkout at Lulu.com.

Here is Lulu's fine print on the coupon code:

Offer valid on orders placed within the United States only. Enter code ‘MEMORIAL09’ during checkout and save $5.00 off any purchase of $25.00 or more. Discount cannot be used to pay for, nor shall be applied to, applicable taxes or shipping and handling charges. Promotional codes cannot be applied to any previous orders. No exchanges or substitutions allowed. Only one valid promotional code may be used per account. Offer valid from 05/22/09 through 05/25/09 at 11:59 PM GMT. Lulu.com reserves the right to change or revoke this offer at any time. Void where prohibited. Please note that coupon code is case-sensitive.

Death to Recipes!

2009-05-19T11:17:00.000-04:00

I love food. I enjoy cooking and I especially enjoy eating. One of my favorite web sites is epicurious.com, and the kitchen shelf devoted to cookbooks sags alarmingly. Many Saturday mornings, you will find me here.

But I am not happy about how recipes have insinuated themselves into my work life. For some reason, the recipe is the default example of structured content. Look at what happens when you search Google for xml recipe example. Recipes are everywhere, not unlike high fructose corn syrup. Unfortunately, I am not immune to the XML recipe infiltration myself.

I understand the appeal. Recipes are:

highly structured content
well understood

But I think the example is getting a little tired and wilted. Let's try working with something new. Try out a new kind of lettuce, er, example. This week, I'm trying to write a very basic introduction to structured authoring, and I'm paralyzed by my inability to think of any non-recipe examples.

I'm considering using a glossary as an example. After all, it's a highly structure piece of content whose organization is well understood. Maybe I'll use food items as my glossary entries. Baby steps...

PS It's totally unrelated, but this article about two chefs eating their way through Durham ("nine restaurants in one night, at least five hours of eating and drinking") is quite fun.

DocTrain's demise and a challenge to presenters

2009-05-18T16:13:00.000-04:00

Unfortunate news in my inbox this morning:

I regret to announce that DocTrain DITA Indianapolis is cancelled. DocTrain/PUBSNET Inc is shutting down.

As a business owner, messages like this strike fear in my heart. If it could happen to them...gulp. (This might be a good time to mention that we are ALWAYS looking for projects, so send them on over, please.) My condolences to the principals at DocTrain.

Meanwhile, I'm also thinking about what we can do in place of the event. I had a couple of presentations scheduled for DocTrain DITA, and Simon Bate was planning a day-long workshop on DITA Open Toolkit configuration.

So, here's the plan. We are going to offer a couple of webinars based on the sessions we were planning to do at DocTrain DITA:

Demystifying DITA to PDF Publishing, June 2, 11 a.m. Eastern time (Sarah O'Keefe)
Hacking the DITA Open Toolkit, June 4, 11 a.m. Eastern time (Simon Bate)

Each webinar is $20. We may record the webinars and make the recordings available later, but I'm not making any promises. Registration is limited to 50 people.

Here's the challenge part: If you were scheduled to present at DocTrain DITA (or weren't but have something useful to say), please set up a webcast of your presentation. It would be ultra-cool if we could replicate the event online (I know that the first week in June was cleared on your schedule!), but let's get as much of this content as possible available. If you do not have a way to offer a webinar, let me know, and I'll work with you to host it through Scriptorium.

And here's my challenge to those of you who like to attend conferences: Please consider supporting these online events. If $20 is truly more than you can afford, contact me.

Get 10 percent off a printed copy of Technical Writing 101

2009-05-15T12:25:00.003-04:00

If you have been waiting for a discount to purchase a printed copy of the third edition of Technical Writing 101, now is your chance. Through May 31, 2009, use the code MAYCONTEST10 during checkout to get 10 percent off when buying a printed copy from Lulu.com. The printed version is $35.95 (before the discount). FYI: the discount isn't applied to shipping or taxes.

Technical Writing 101 is also available as a $20 download from our online store (but the Lulu discount doesn't work there).

By the way, if you received a coupon code for entering our contest, use that code now! The discount code expires today.

Technical Writing 101 contest: and the winners are...

2009-05-08T11:30:00.001-04:00

Congratulations to Ravindra Kumar, Judy Walters, and Axel Regnet, who each won a free download of Technical Writing 101. As a thank-you to entrants who didn't win a free copy, we offered a $5 discount off the $20 price.

All entrants should have received an email with a coupon code for a free download or $5 off. We appreciate your interest in our books.

Back from Atlanta, STC wrapup

2009-05-07T17:02:00.000-04:00

The STC Summit was fun as always. My slides are below, but first some other observations.

David Pogue was an excellent keynote speaker. And he sang!

Attendance was lower than last year, but traffic at our booth (and others from what I heard) was up. I think this was a combination of a better location for exhibitors, shorter exhibit hours (Wednesday was cut), and perhaps more senior and more serious attendees.

The biggest change from previous years had to be the use of social media in general, but especially Twitter:

The #stc09 hashtag got a serious workout, the tweetup drew 50 or 60 people, and there was constant chatter about the conference online.
There was a complementary online event, #stcnotthere.
As we were leaving the conference in sketchy weather, #stuckinATL_stc09, created by @lisajoydyer, helped us chronicle the various airport delays and find each other at the airport. It made the delays almost bearable.
Rachel Hougton's flickr feed captures the feel of the entire event, ranging from the Georgia Aquarium and the World of Coca-Cola to the honors banquet and lots of casual photos. (great job, Rachel, btw)
You can find a collaborative liveblog on scribblelive.

Interestingly, it seems as though fewer people blogged the event; instead, they were tweeting. However, Keith Soltys did put up day-by-day summaries on Core Dump, and Gryphon Mountain Journals has some reactions. I was unable to find any other live-blogging; if I missed you, please leave a comment.

Tom Johnson interviewed numerous people (including me) at the event. His interview with Ginny Redish is already available.

The tweeting and other social media augmented the actual event. There were people tweeting for lots of reasons: to solve problems (chairs needed), organize groups for dinner, provide sound bites from presentations, and more. The organizing committee put up a twitter feed on a monitor next to their booth and got lots of attention.

I get the impression that the tweets gave non-attendees a flavor of the event. If you were following #stc09 but not attending, did this make you more likely to consider attending in 2010?

Ironically, one of my presentations was actually about technical communication and Web 2.0 issues. I have a white paper on this topic, which is far more useful than the slides. (OK, if you insist, the slides are also available.)

My second presentation was presumptuously entitled "The State of Structure." This presentation discusses the results of our industry survey on structured authoring, which was conducted in January and February 2009.

The State of Structure

View more presentations from Scriptorium.

If you want more information, the survey report is $200 and available in our store.

Enter today: Technical Writing 101 giveaway ends tomorrow

2009-05-06T11:59:00.004-04:00

We are closing our drawing for free downloads of Technical Writing 101 tomorrow. If you haven't already entered the contest, enter today. We'll pick three winners and notify them via email on Friday.

If you want to sneak a peek at what's in the new edition, you can read the table of contents and excerpts from two chapters (PDF), and you can see the preview provided by Google Book Search. (Be forewarned that some pages in the Google preview weren't processed cleanly, but they are still readable.)

Technical Writing 101 is now available. Win a free download!

2009-04-29T15:23:00.006-04:00

Technical Writing 101 (third edition) is now available for purchase! You can instantly download the PDF version from our online store for $20, or you can order a printed copy from Lulu.com for $35.95. We're also offering a site license for $250: you can download the PDF version and distribute it up to 20 people.

To celebrate the book's release, we're giving away three downloads of the book. Enter the drawing by May 7. We'll notify the winners via email.

Enter the drawing today!

If you're an instructor and would like to review the book for your classes, contact us at books@scriptorium.com. In your message, tell us about the courses for which you're considering the book and how many students attend those classes each year.