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:

1. Write page one.
2. Send page one for edits.
3. Get page one edited, reviewed, and so on.
4. Send page one to the printer.
5. Write page two.
6. Send page two for edits.
7. and so on…

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.

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:

• How many of our colleagues in other departments think we spend our lives stringing together fancy words?
• Even worse, how many of those in upper management have the same thoughts?
• What are we all doing to end these perceptions?

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.

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.

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.)

XML as a conversion tool

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 already has the ability to generate XML from the database.
• We took the generated XML and processed it with an XSLT transform to create XML that is FrameMaker-friendly. (For example, tables are set up as CALS tables in the processed content.) We also excluded some content in this step.
• In FrameMaker, we built a structured application that imports the custom XML and formats it to match the existing unstructured FrameMaker files.

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.

XML as a publishing gateway

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.

Custom XML for unique requirements

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:

• The DITA content model is much more complex than what Cinnamon needs.
• The DITA Open Toolkit is much more complex than what Cinnamon needs.
• The various DITA CMSs are bigger than what Cinnamon wants (which eliminates one major advantage of DITA—the ready availability of CMS solutions).

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:

• The use of XML (and not DITA) to solve business problems related to technical communication
• Heavy reliance on custom programming
• Heavy reliance on open standards (particularly XSLT and Ant)

Is this a trend? I hope so, because these projects have been fascinating to implement.

What do you think?

* Not their real name.

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.

The discussion also includes questions and feedback from the audience.

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:

• Keep it simple. Say what you want to say and be done with it.  Include well defined headings and separate your content into readable chunks.  Often, flashy extras designed to make information look pretty can create frustration for screen reader users.
• Good color contrast. Foreground colors should be easy to read over the background colors. AccessColor is a good color contrast analyzer for websites.
• Captioning or transcripts. Videos should be captioned, or include a transcript alternative.  YouTube offers a captioning option.  This extra step is helpful for the deaf and hard of hearing, and also allows those who are in a setting where audio is not appropriate, to still get the most from the video.
• Labels. All images and tables that display useful content should have a description with the basic point the image or table is trying to portray.  Screen readers such as JAWS for Windows rely on these descriptions.  They are also helpful for browsers with images disabled.
• Text size adjustment.  Most modern browsers allow for text size adjustments through the “ctrl ++” or “ctrl -” commands.  Use text wraps to prevent the text from crowding when enlarged.
• Keyboard navigation. Provide keyboard access points to allow screen reader users and other non mouse users to navigate through the page. Include a skip content option so that the keyboard commands don’t have to slog through unwanted information.

Additional resources

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.