When you implement a DITA-based workflow, you face myriad new challenges, such as getting accustomed to topic-based writing, exploring reuse strategies, and specialization. The most difficult technical obstacle is usually setting up a PDF/print publishing workflow. The DITA Open Toolkit provides very basic PDF output, but for organizations who require attractive, professional-looking PDF content, extensive and expensive customization is required. FrameMaker is easier to configure than the Open Toolkit and produces lovely PDF files, but can you work around the limitations of the DITA support? InDesign offers the highest quality typography but has significant limitations in working with structured content. This session discusses the advantages and disadvantages of each approach to extracting PDF from DITA content.
This session is intended for individuals who are considering a DITA implementation and expect to need PDF output. Basic familiarity with DITA, XML, and related technologies is helpful but not required.
NOTE: During the recording, the presenters will mention polls. You will not see these polls while viewing the recording, but the presenters will describe the results.
Clay Shirky has a fascinating post on the concept of algorithmic authority; the idea that large systems, such as Google PageRank or Wikipedia have authority (that is, credibility) because of the way that the system works. In other words, a page that is returned first in a Google search is assumed by the searcher to be more credible because it is ranked first.
That made me think about authority in technical content.
As an in-house technical writer, your words have authority and your content carries the corporate logo. But although this should theoretically increase your credibility, it seems that the reverse is true. Consider, for instance, the following hypothetical book titles:
XYZ User’s Guide—This document, produced by the makers of XYZ, is shipped in the product box (or downloaded as a PDF with the software)
XYZ Classroom in a Book—This document is available in bookstores and is produced by XYZ Press
XYZ: The Complete Reference*—This document is available in bookstores and is produced by a third-party publisher
Which of these books would you turn to for help? What are your expectations of each document?
I believe that credibility and thus authority increases with distance from the product’s maker. In other words, the third-party book has more authority than either of the other two. Credibility is compromised by close association with the organization that makes the product.
When we apply this concept to information on the web, the implications are troubling for professional content creators who work inside corporations. If corporate authorship decreases authority, we get this result:
online help < user forums on corporate site < user forums on third-party site
Will people looking for user assistance gravitate toward independent third-party sites? What does that mean for in-house authors? How can you increase your credibility as a corporate technical communicator?
* Feel free to substitute your favorite book series title: XYZ for Dummies, XYZ: The Missing Manual, The Complete Idiot’s Guide to XYZ, XYZ Annoyances, …. I should probably also mention that I have written both a Dummies book and a Complete Reference.
Many thanks to all of the people who attended yesterday’s webcast on coping with user-generated content.
We recorded the webcast, and it is now available:
In a nod to the topic itself—and in an effort to make the event more interesting, I solicited quite a bit of audience participation. As a result, I owe the webcast participants a significant number of links and other resources.
Question: What blogs do you read?
Answer: Lots.
Better answer: Here is a link to my Google Reader subscriptions in the Publishing category. Many thanks to the attendee who recommended sharing them this way. (If you’d like full credit by name, send me email or put a note in the comments; I don’t want to do that without permission.) I’ve also listed the blogs at the bottom of this post.
In addition to the publishing blogs, I specifically mentioned Punk Rock HR, Dooce, and Mark Logic CEO blog. (Don’t read the first two if you are offended by a word that starts with F.)
Question: Are there any guides to legal issues in social media, such as libel?
Answer: I found a few interesting resources, but not a definitive guide.
Request for Proposal (RFP) documents usually arrive in the dead of night, addressed to sales@scriptorium or sometimes info@scriptorium.
Dear Vendor,
LargeCompany is looking for a partner who can work magic and walk on water. Please refer to the attached RFP.
Signed,
Somebody in Purchasing
Our instinct is to crack open the RFP and start writing a proposal. But over time, we’ve learned to take a step back and evaluate the RFP first to ensure that it’s worth our time.
In this post, I’ve outlined some of the issues that we consider before responding to an RFP.
(This post is late. In my defense, I had the flu and the glow of the computer monitor was painful. Also, neurons were having trouble firing across the congestion in my head. At least, that’s my medical explanation for it. PS I don’t recommend the flu. Avoid if possible.)
Which of these scenarios do you think is most intimidating?
Giving a presentation to a dozen executives at a prospective client, which will decide whether we get a project or not
Giving a presentation to 50 people, including half a dozen supportive fellow consultants
Giving a presentation to 400 people at a major conference
I’ve faced all three of these, and while each scenario presents its own set of stressors, the most intimidating, by far, is option #2.
In general, I’m fairly confident in my ability to get up in front of a group of people and deliver some useful information in a reasonably interesting fashion. But there is something uniquely terrifying about presenting in front of your peers.
At LavaCon, I faced the nightmare—a murderers’ row of consultants in the back of the room, fondling various tweeting implements.
Here are some of the worst-case scenarios:
No new information. I have nothing to say that my colleagues haven’t heard before, and they could have said it better.
Disagreement. My peers think that my point of view is incorrect or, worse, my facts are wrong.
Boring. I have nothing new to say, my information is wrong, and I’m not interesting.
Of course, my peers were gracious, participated in the session in a constructive way, and said nice things afterwards. I didn’t even see any cheeky tweets. (I’m looking at you, @scottabel.)
All in all, I’d have to say that it’s a lot more fun to sit in the back of someone else’s presentation, though. Neil Perlin handled his peanut gallery deftly, asking questions like, “With the exception of the back row, how many of you enjoy writing XSLT code?”
Rahel Bailie said it best, I think. After completing her excellent presentation, she noted that presenting in front of peers is terribly stressful because, “I really want you to like it.”
In addition to our November event on localization, we are adding another webcast in December. I’ll be presenting Strategies for coping with user-generated content on December 8 at 11 a.m. Eastern time via GoToWebinar. This event is free but registration is required.
Here’s the description:
The rise of Web 2.0 technology provides a platform for user-generated content. Publishing is no longer restricted to a few technical writers—any user can now contribute information. But the information coming from users tends to be highly specific.
The two types of information can coexist and improve the overall user experience. User-generated content also offers an opportunity for technical writers to participate as “curators”—by evaluating and organizing the information provided by end users.
Remember, there’s no charge to attend, but you do need to register.
October 22nd, join Simon Bate for a session on delivering multiple versions of a help set without making multiple copies of the help:
We needed to generate a help set from DITA sources that applied to multiple products. However, serious space constraints prevent us from using standard DITA conditional processing to create multiple, product-specific versions of the help; there was only room for one copy of the help. Our solution was to create a single help set in which select content would be displayed when the help was opened.
In this webcast, we’ll show you how we used the DITA Open Toolkit to create a help set with dynamic text display. The webcast introduces some minor DITA Open Toolkit modifications and several client-side JavaScript techniques that you can use to implement dynamic text display in HTML files. Minimal programming skills necessary.
I will be visiting New Orleans for LavaCon. This event, organized by Jack Molisani, is always a highlight of the conference year. I will be offering sessions on XML and on user-generated content. You can see the complete program here. In addition to my sessions, I will be bringing along a limited number of copies of our newest publication, The Compass. Find me at the event to get your free copy while supplies last. (Otherwise, you can order online Real Soon Now for $15.95.)
Register for LavaCon (note, early registration has been extended until October 12)
And last but certainly not least, we have our much-anticipated session on translation workflows. Nick Rosenthal, Managing Director, Salford Translations Ltd., will deliver a webcast on cost-effective document design for a translation workflow on November 19 at 11 a.m . Eastern time:
In this webcast, Nick Rosenthal discusses the challenges companies face when translating their content and offers some best practices to managing your localization budget effectively, including XML-based workflows and ways to integrate localized screen shots into translated user guides or help systems.
Because of a Series of Troublesome Committees, I find myself thinking about three big-picture concepts: strategy, tactics, and execution:
Strategy is the overall plan. For example, one strategy for getting new projects at Scriptorium is to establish ourselves as experts in our chosen field.
Tactics are specific actions to achieve the plan. Our tactics include writing articles and delivering conference presentations that buttress our claim of expertise.
Execution is what happens after you pick a strategy and develop some tactics. That’s when we write the articles and attend the conferences.
Each of these stages is a prerequisite for the other. That is, you start by developing a strategy and can then pick your tactics. Finally, you have to execute on the plan.
You can fail at every point in the process:
Choose the wrong strategy, and not much else matters. Great tactics and excellent execution will not rescue you if you have chosen the wrong approach.
If you have the right strategy, but the wrong tactics, you may have some limited success, but poor tactics will work against you.
Worst of all, though, is bad execution. You pick the right strategy and the right tactics, and then sabotage the whole thing with poor follow-through or lousy performance. For example, writing an article full of bad grammar or delivering a boring, technically inaccurate presentation would be bad execution for us.
At every stage, you face constraints. For instance, if your budget is limited, you might not be able to justify the most expensive tactic, even though it might have been the most effective. But once you work through your constraints and choose your tactics, there’s really no excuse for doing those activities badly.
Some things to keep in mind when working with technical communicators:
Forget the spin. Exorcising marketing and PR messages from technical content is a core job skill for many of us. Simple, honest, and straightforward messages are better. If you try to spin your message, expect a scornful response.
Language matters. Writers become writers because they care about language. If you want their respect, you need to show that you also care about language. At a minimum, grammar and mechanics need to be accurate. If you can go beyond the basics and demonstrate graceful writing, you will score bonus points.
My latest XML Strategist article, “The ABCs of XML,” is available as a PDF file (144K). This article was originally published in the September/October 2009 issue of Intercom.
The technical side of XML is not much more difficult than HTML; if you can handle a few HTML angle brackets you can learn XML. […] If […] you don’t like using styles and
prefer to format everything as you go, you are going to loathe structured authoring.
Just trying to make sure that there are no surprises. The article itself is a very basic introduction to the principles that make XML important for technical communication: automation, baseline architecture (sorry…I had problems with B), and consistency.
In addition to a gratuitous (and entertaining) swipe at “noisome” DITA “fanboys,” Roger Hart argues that we need to reconsider the disadvantages of automated formatting:
The thing is, [separation of content and formatting has] all been taken rather stridently to heart in certain quarters, leading to a knee jerk reaction whenever author-controlled formatting/pagination/lineation is mentioned as anything other than bleak, sulphurous devilry. This is twaddle. […]
Uncertainty in meaning is anathema to user intelligibility. If we’re going to make sure we’re not writing poetry, there’s definitely value in having poetry’s level of control over semantic blocks.
Of course, it’s fully possible that this is an expensive distraction.
Possible? It’s definitely expensive. It’s possible that it’s a distraction.
I think Hart perhaps unintentionally put his finger on the real issue: value. How much value (in the form of improved comprehension) is added to a technical document when you are able, in the words of commenter Brian Harris, to “lovingly handcraft” each page?
How much value (in the form of cost avoidance) is added to an organization when you are able to spit out a reasonably formatted document in a few minutes?
Actually, I have a different question. How far should we take this argument? Here’s an example of the pinnacle of handcrafting:
You can just imagine the scribes with their quills, lapis, gold leaf, and other implements muttering, “That Gutenberg and his noisome fanboys. He can’t even render two colors without our help. Poser. It’ll never last.”
Formatting automation removes cost from the process of creating and delivering content. For technical documents that change often and are perhaps delivered in multiple languages, it removes a lot of cost. Let’s assume that handcrafted pages can improve ease of reading and comprehension with careful copy-fitting and adjusted spacing (Hart’s article mentions “headings, line breaks, intra-word, etc”). This increases the cost of the content.
What happens when content is expensive? Fewer people get to see it.
I think we can all agree that e-books offer none of the typographic sophistication in question here. Bill Gates (yes, that Bill Gates) wrote in 1999:
It is hard to imagine today, but one of the greatest contributions of e-books may eventually be in improving literacy and education in less-developed countries. Today people in poor countries cannot afford to buy books and rarely have access to a library.
Essentially, we can produce documents inexpensively and give more people access to them as a direct result of lower cost, or we can climb on our typographic high horse and whine about word spacing.
To provide the best experiences, we use technologies like cookies to store and/or access device information. Consenting to these technologies will allow us to process data such as browsing behavior or unique IDs on this site. Not consenting or withdrawing consent, may adversely affect certain features and functions.
Functional
Always active
The technical storage or access is strictly necessary for the legitimate purpose of enabling the use of a specific service explicitly requested by the subscriber or user, or for the sole purpose of carrying out the transmission of a communication over an electronic communications network.
Preferences
The technical storage or access is necessary for the legitimate purpose of storing preferences that are not requested by the subscriber or user.
Statistics
The technical storage or access that is used exclusively for statistical purposes.The technical storage or access that is used exclusively for anonymous statistical purposes. Without a subpoena, voluntary compliance on the part of your Internet Service Provider, or additional records from a third party, information stored or retrieved for this purpose alone cannot usually be used to identify you.
Marketing
The technical storage or access is required to create user profiles to send advertising, or to track the user on a website or across several websites for similar marketing purposes.
To provide the best experiences, we use technologies like cookies to store and/or access device information. Consenting to these technologies will allow us to process data such as browsing behavior or unique IDs on this site. Not consenting or withdrawing consent may adversely affect certain features and functions.
Functional
Always active
The technical storage or access is strictly necessary for the legitimate purpose of enabling the use of a specific service explicitly requested by the subscriber or user, or for the sole purpose of carrying out the transmission of a communication over an electronic communications network.
Preferences
The technical storage or access is necessary for the legitimate purpose of storing preferences that are not requested by the subscriber or user.
Statistics
The technical storage or access that is used exclusively for statistical purposes.The technical storage or access that is used exclusively for anonymous statistical purposes. Without a subpoena, voluntary compliance on the part of your Internet Service Provider, or additional records from a third party, information stored or retrieved for this purpose alone cannot usually be used to identify you.
Marketing
The technical storage or access is required to create user profiles to send advertising, or to track the user on a website or across several websites for similar marketing purposes.
