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.
We have opened up free access to two of our white papers:
Hacking the DITA Open Toolkit, available in HTML or PDF (435 KB, 19 pages)
FrameMaker 8 and DITA Technical Reference, available inPDF (5 MB, 55 pages)
These used to be paid downloads.
Why the change of heart? Most of our business is consulting. To get consulting, we have to show competence. These white papers are one way to demonstrate our technical expertise.
(By this logic, our webcasts should also be free, but I’m not ready to go there. Why? We have fixed costs associated with the webcast hosting platform. Plus, once we schedule a webcast, we have to deliver it at the scheduled time, even if we’d rather be doing paying work. By contrast, we can squeeze in white paper development at our convenience.)
What are your thoughts? We are obviously not the only organization dealing with this issue…
If you are reading this, then we have succeeded in migrating our web site over to WordPress.
Of course, the process of managing our own content always takes a back seat to working with our customers’ content, so the process took longer than you might expect.
We did learn a couple of things, most of which should sound awfully familiar if you are working on your own content strategy:
It’s not until you try to move into a new system that you recognize all the mistakes you made the previous system.
PHP stands for Picky Hypochondriac Programming. I had several cases where code absolutely refused to work for no apparent reason. I had the resident PHP expert (Simon) look it over. Eventually, I gave up and retyped the code, and then it worked.
Learn to work with the tool and not against it. I have to credit a former coworker, Bruce Bicknell, for this little gem, which he originally applied to Word versus FrameMaker. When moving from Dreamweaver-based HTML to WordPress, take some time to learn best practices for WordPress. Don’t try to impose your existing Way of Doing Things onto the new system. It’s inefficient and it probably won’t work.
Content migration is always awful. To transfer our blog, I found a blogger-to-WordPress converter. That worked pretty well, except that a couple of posts now have my name on them even though I didn’t write them. Transferring comments was a travesty that involved the support people at Haloscan (helpful) and cleaning out random comment triplication (gross manual labor).
But I hope you like the new site and blog. Please poke around and leave us feedback.
For August and September, our webinar schedule is as follows:
DITA 101, August 18 at 11 a.m. Eastern time
Participants will learn about basic Darwin Information Typing Architecture (DITA) concepts, the business case for implementing DITA, and some typical uses of DITA. This webinar is ideal for those who are considering a move to structured authoring based on the DITA standard. Register
Demystifying DITA to PDF Publishing, September 10 at 11 a.m. Eastern time
When a company implements a DITA-based workflow, the most difficult technical obstacle is often setting up a PDF/print publishing workflow. This session discusses the advantages and disadvantages of using the DITA Open Toolkit, FrameMaker, InDesign, and other options to create PDF output from DITA content. Basic familiarity with DITA, Extensible Markup Language (XML), and related technologies is helpful but not required. Register
What Do Movable Type and XML Have in Common?, September 22 at 11 a.m. Eastern time
The invention of movable type changed the economics of information by making the process of copying a book by hand obsolete. More than 500 years later, XML seems to be doing the same to desktop publishing. But where movable type changed the economics of a mechanical process—creating printed copies—XML changes the economics of content authoring, formatting, and customization. This webinar takes a look at how publishing technologies revolutionize the way people consume information and how those technologies affect authors. Register
Each webinar is $20.
During the sessions, you can interact with the presenter and other students through the chat interface or the audio connection. There is a question-and-answer session at the end of each webinar. The Q&A is not included in session recordings, which are available for download later. Participants in the sessions receive a free recording.
To register for these webcasts, or to purchase recordings of past webinars, go to our online store.
Conversation and Community: The Social Web for Documentation (XML Press, ISBN: 9780982219119) by Anne Gentle provides technical communicators with a roadmap for integrating social media — blogs, wikis, and much more — into their content development efforts. This is critical because, as Anne notes in the preface, “professional writers now have the tools to collaborate with their audience easily for the first time in history.”
Anne provides overviews of all the major social media concepts — from aggregation to syndication, wikis, discussion, presence, and much more. But it is Chapter 3, “Defining a Writer’s Role with the Social Web,” that will make this book a classic. Here, Anne lays out a detailed strategy for determining whether and how to introduce social media in an organization. Consider this:
It’s important to find a balance between allowing an individual’s authentic voice to speak on behalf of an organization and the requirements of institutional messaging and brand preservation. […] It’s also possible that you are ahead of the curve and need to help others see ways to apply social technologies for the company.
She goes on to explain just how to accomplish these things.
Wikis and blogs each get a chapter of their own, in which Anne discusses how to start and maintain these types of environments.
After reading so much of Anne’s work on her blog, it’s a bit odd to see her writing on paper in an actual book. The feeling that I’ve wandered into the wrong medium is augmented by extensive footnotes, most of which point to web site resources, and the many examples of web-based content (such as videos or interactive mashups). However, it’s likely that the book’s target audience is more comfortable with paper.
Conversation and Community: The Social Web for Documentation provides an excellent introduction to wikis, blogs, forums, and numerous other social media technologies for the professional content creator. There is valuable (and perhaps career-preserving) information about how to develop a strategy for user-generated content that is compatible with your organization’s corporate culture.
If you think that community participation in your documentation is coming soon, read this book immediately. If you think that it’s not coming, you’re wrong, and you especially need to read this book.
“I can write in anything.” “The tool doesn’t matter.” “I can learn any new tool.”
Most of the time, I agree. But then, there are the exceptions.
One of our customers is using FrameMaker to produce content that is delivered in HTML. (They use structured FrameMaker, generate XML, and then transform via XSLT into HTML.) Their rationale for using FrameMaker was:
The project was on an extreme deadline.
The writers already knew FrameMaker.
FrameMaker is already installed on the writers’ systems.
All valid points.
But.
We have had a continuous stream of requests from the writers to make adjustments to the FrameMaker formatting. Things like “the bullets seem a little too far from the text; can you move them over?”
FrameMaker is being used as an authoring tool only. FrameMaker formatting is discarded on export; HTML formatting is controlled mainly by CSS. However, even after repeated explanations, we continue to receive requests to modify the FrameMaker formatting.
In this specific case, the authoring tool does matter. Writers are focusing on the wrong set of issues (leading, kerning, print formatting), none of which is actually relevant for the output.
Why are they focused on this stuff? Because they can. It seems to me that moving authors to a WYSIOO (what you see is one option) tool, such as oXygen or XMetaL, instead of a WYSIWYG tool (FrameMaker) would eliminate the obsession with irrelevant formatting.
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.
