Site FeedPalimpsest
Congratulations to contest winners...
Wednesday, July 01, 2009 — posted by Alan Pringle
...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.
Labels: book, technical writing
1:27 PM Permalink | |
This is the future of technical communication
Monday, June 29, 2009 — posted by Sarah O'Keefe
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 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.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?
What colors would you like to see? We do have two dozen available, see this list.
- Joe in TechComm
Labels: web 2.0
10:39 AM Permalink | |
Enter soon: Technical Writing 101 contest ends tomorrow
— posted by Alan Pringle
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.
Labels: book, print on demand, technical writing
8:05 AM Permalink | |
Win a printed copy of Technical Writing 101 (third edition)
Wednesday, June 24, 2009 — posted by Alan Pringle
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.
Labels: book, technical writing
10:01 AM Permalink | |
Automated trademarking in structured documents – DITA in particular
Monday, June 22, 2009 — posted by David J. Kelly
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?
Labels: trademark
1:21 PM Permalink | |
Whither STC?
Friday, June 19, 2009 — posted by Sarah O'Keefe
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
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.
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
Labels: STC
4:11 PM Permalink | |
Flare 5 DITA feature review, part 2
Wednesday, June 17, 2009 — posted by Sarah O'Keefe
[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.
2:00 PM Permalink | |