May 15th, 2012 by ScriptoriumTech
In this webcast recording, George Bina shows you how to create DITA content from zero to a full deliverable using oXygen. The full deliverable leads to multiple publishing formats.
May 15th, 2012 by Sarah O'Keefe
The batch publishing paradigm is deeply ingrained in technical communication, and breaking out of it is going to make the transition from desktop publishing to structured authoring look easy.
I wish this were my idea, but I think it was Mark Baker from whom I first heard about this issue. There’s a discussion in the comments of his It’s Time for a New Doctrine of Technical Communication article about “wedding day publishing” which he describes as:
“months of planning [...] executed in a [...] desperate panic lest any missed detail should spoil the immortal memory of the great day”
Instead, Mark says we need
a system that is always in a publishable state, and in which publication is not a great event, but a normal part of everyday life
Nearly all of our technical communication tools are intended for “deliverables.” That is, you work on a book, help system, web site, or other unified presentation of a lot of content and at some point, you push the Big Red PUBLISH button. Of course, this system makes a good bit of sense in a print world, where creating a book involves messy manufacturing processes—paper, ink, glue, not to mention a printing press.
It’s like cupcakes. Producing two dozen cupcakes is pretty much the same amount of work as producing a single cupcake, so it makes sense to create them all at once.
Imagine producing a book in small increments. You would:
This is pretty clearly not going to work for anything more than two pages of content. But in a digital environment, we can do exactly this—write a small amount of content and make it available to our readers as soon as it is ready. Not only that, it’s quite easy to go back and fix stuff. If, for example, there is a typo in this post (notice that I did not use the subjunctive there [UPDATE: found one!]), I can fix the typo after the initial publication and only those of you who follow our blog obsessively will ever know about it. (And there aren’t THAT many of you.)
Our technical communication paradigm must move away from the 500-year batch publishing habit and toward a nimble just-in-time publishing model.
Most web publishing works this way. Applications like WordPress, Drupal, and others assume that you publish small bits of content frequently. But most technical communication tools assume that you publish large amounts of content infrequently.
We must develop processes that close the gap between tech comm and our readers by eliminating time-consuming processes and publishing content in small increments.
May 11th, 2012 by Alan Pringle
It can be a mightily sucktacular experience when you discover what other people think technical communicators do.
Case in point: a blog post from a college student came up in my Google feeds about tech comm. The post (to which I won’t link because it’s not fair to the author) was about word choice and how the author doesn’t understand why so many writers use big words when smaller words suffice. Yep, I’m with him on that.
OUCH! (flickr: ansik)
That’s when the author threw a punch right into the face of our profession without even knowing it. In a nutshell, he said that technical writing is exempt from the requirements of using basic language.
I think I know what the writer was trying to say: technical writing can require the use of advanced terminology. He meant no intentional malice or disrespect. Even so, his post made it clear he does not entirely understand what we do in tech comm, particularly now that the field has changed so much in past decade or so.
This lack of understanding on one student’s part generated many questions in my mind:
Truly good technical content requires us to break out of our cubicles and collaborate with other departments. Our professional well-being also depends on that collaboration to dispel myths about what we do—and to reinforce the value we provide.
May 4th, 2012 by Alan Pringle
Kindle sales will cannibalize print sales.
That’s what I expected when we released Technical Writing 101 in Kindle format, but numbers from the first quarters of 2011 and 2012 are showing something different.
We made the Kindle version available in early February 2011, so I compared the United States sales for the February/March periods of 2011 and 2012. During that window of time in 2012, we actually sold a few more printed copies than in 2011! I wasn’t surprised, though, to see that Kindle sales went up quite a bit more in 2012:
Print sales of Technical Writing 101 went up by 3.5 percent, and Kindle sales increased by 15.2 percent. So much for my cannibalism theory.
Do these numbers reflect what’s going on in the entire publishing industry? Probably not. Technical Writing 101 is a niche title; I refer to it as the “anti-textbook of technical writing.” The steadier print sales are likely driven by students buying the printed book for college classes.
Our recent survey on ebooks about technical communication showed that 55.2 percent of the respondents read ebooks in the Kindle format, and 43.7 percent of those surveyed were using e-ink Kindle devices. I suspect those numbers in combination with the lower price point for the Kindle edition ($9.99 versus $20–$36 for print, depending on discounts) account for the increasing Kindle sales.
I’m glad to see that the book is reaching more people regardless of the format, and I will be interested to see how the numbers for 2013 compare. Considering my incorrect assumption that Kindle sales would immediately eat into print sales, I won’t make any prognostications right now. But I will leave you with some musical fun from The Buggles:
Buggles – Video Killed Radio Star by bebepanda
P.S. Authors and publishers: I’d love to hear about how Kindle sales have affected your print sales. Leave a comment about your experience.
May 2nd, 2012 by Sarah O'Keefe
There’s more to XML for technical communication than just DITA.
Much of the industry chatter revolves around DITA content management, DITA tools, the vagaries of the DITA Open Toolkit, and DITA implementation hurdles. At Scriptorium, a steady (and large) percentage of our work is DITA-based. But there are lots of things you can do with non-DITA XML that are relevant to technical communication. This post describes a few creative solutions; perhaps they will help you think creatively about your options.
(All names and some project specifics changed.)
Our first customer (let’s call them the Allspice* Company) has a custom database, which the technical writers have no control over. The database contains information needed, in somewhat different form, for the user documentation. The documentation is currently in unstructured FrameMaker, and one of the chapters contains all of the database-derived information.
Here’s what we did:
Allspice can now export content from the database and bring it into FrameMaker as a fully formatted structured FrameMaker file. That structured file is then included in a book with the unstructured FrameMaker content. This process is completely automated and eliminates manual maintenance of the database-derived content in FrameMaker.
To me, this project was especially interesting because XML is just a convenient intermediate format. There’s no structured authoring involved.
Another customer, Basil Corporation*, is using XML as a gateway to other formats. Once again, there is information in the organization that the technical writers must publish, but the writers do not control the source files for that information. In this case, Basil has XML files that use a custom structure. We preprocessed the files to (again) produce XML that is more usable from a content point of view. We then wrote (another) FrameMaker structured application for PDF output and a transformation that produces man pages (nroff files). Once again, there’s no actual XML-based authoring—just XML being used to extract the needed deliverables.
For a project for Cinnamon, Inc.*, we have topic-based content, which needs to be delivered in very simple HTML5. We ruled out DITA as a source format for a variety of reasons. The ones I can discuss are:
Cinnamon needs to manage a lot of metadata, but the content itself is straightforward. Here, the solution will be a custom content model that provides what Cinnamon needs (and nothing else), along with an open-source tool stack. Yes, there will be a lot of custom programming, and I spent a good bit of time looking for a packaged (commercial or open-source) solution that meets Cinnamon’s requirements, but in the end, we realized that a bare-metal custom build was going to be the most efficient option given their requirements.
These three projects have something in common:
Is this a trend? I hope so, because these projects have been fascinating to implement.
What do you think?
* Not their real name.
April 27th, 2012 by ScriptoriumTech
In this video recording, guest presenter Sarah Maddox explains why collaboration is a good thing, why a wiki is a good solution for it, and how to do it on Confluence.
April 23rd, 2012 by Sarah O'Keefe
We all know that Lorem Ipsum is not your friend. But sometimes, even sample content fails.
Recently, I needed to build a prototype HTML site design that included section navigation.
We built out a wireframe based on sample content provided by our customer. The whole thing worked fine, and they approved it, and off we went to implementation. During testing, we promptly discovered that our navigation wouldn’t work because we actually needed multilevel navigation in the left link list.
The moral of the story? Content drives requirements, and fake content gives you fake requirements.
April 18th, 2012 by Sarah O'Keefe
In this interactive session, technical communication experts Sarah O’Keefe, Nicky Bleiel, and Tony Self give their opinions about important current topics in the industry.
The discussion also includes questions and feedback from the audience.
April 17th, 2012 by Simon Bate
Simon Bate provides a planning framework for implementing an XML-based structured authoring environment.
April 16th, 2012 by Holly Mabry
Accessibility is a term commonly associated with the process of making content available for people with vision, hearing, and mobility impairments. In reality it should also include the process of making content accessible for everyone regardless of ability or background.
Hello, my name is Holly Mabry. I joined Scriptorium as an intern in the middle of February. One of my biggest interests is working with accessibility issues in relation to electronic information.
One of the biggest mistakes that developers make in terms of accessibility is adding it as an afterthought after the product is finished. It would save a lot of time and money if it was added into the project development cycle from the start.
Here are a few things to think about when developing websites, apps, or any other accessible electronic content:
Web Content Accessibility Guidelines: Official set of web accessibility guidelines from the World Wide Web Consortium.
Section508.gov: Resources for understanding and implementing Section 508. This law requires all federal affiliated websites and other electronic content to be accessible for people with disabilities.
I also keep a fairly exhaustive list of accessibility related resources on my blog: Accessibility and Technology Geek listed under the page Accessibility Resources.
Tech comm problems? Contact us.
Scriptorium Publishing | Post Office Box 12761 Research Triangle Park, NC
27709 | (919) 481 2701 |
info@scriptorium.com
