I refined and refined the language. I made sure each fact was accurately paraphrased and referenced. The article occupied so much of my attention, I worked on it over the weekend, and once late at night. After several days of focusing on practically nothing other than the article, I submitted it to the appropriate person for review.

After reading through the article, the reviewer noted that it was good, but it wasn’t entirely what she had it mind. Whereas I focused on information in the present, she wanted more stories from the past. More stories and anecdotes that show the larger point she wanted to make about the technology.

I returned to my desk, thinking about a new approach. She was right. Somehow, in writing the article, I had neglected story. Story was a key missing element.

The next day, I traveled to the main library for my organization, in downtown Salt Lake, to look for stories from the past. I immersed myself in old books, theses, articles, almanacs, and journals — looking for stories or interesting anecdotes that might illustrate the larger point we wanted to make. You have to read to find stories, or talk to people, I realized. Stories don’t just arrive at your desk while you’re hacking away at the language. You have to look for them as you might look for lost money.

While searching for stories, I realized a thing or two. Story is the form that speaks most clearly to our psyche, but life does not naturally play out in stories. For example, the events of my day are mostly mundane. Today I woke up, worked on some wordpress projects, drove to work, worked on some writing projects, played basketball at lunch, came home, ate lasagna, played in the backyard with my kids,  talked with a client on the phone, watched some TV, and here I am typing this blog post. Not a particularly memorable day. Next week I will remember almost nothing of what happened. It will become a blur in my past, just an average day of life.

If this were the substance of journals, histories, biographies, and other records, no one would read them. They would slip into non-use. It’s our nature to craft the mundane events of our lives into stories. We demand that a person’s life is no mere series of humdrum events. Life is a battle against conflict. It’s an attempt to reach a difficult goal. It’s a struggle to move in a particular direction that resists us. As such, we select the events that matter for that purpose. We heighten the detail that poses the antagonizing force. As we tell the story, we focus on the information that can be bent and shaped into a plot. And then we move towards a defining moment, which if we capture at exactly the right time, changes everything. We do all this even if it does not match history in a matter-of-fact way, because we thirst for story.

While researching and brainstorming stories, I began to see a different story develop than I had originally intended. Leveraging as many details as I could, I made a revision. I found all the ingredients I needed to rewrite the article in an interesting way. And with the help of a colleague, who supplied a fascinating quote, I landed a perfect ten in the conclusion, or so I thought.

The next week I submitted the revision for review. She read it and gave me a brief compliment before noting the purpose she had in mind followed another direction contrary to the position in my article. I still hadn’t really grasped what she wanted. I decided to scrap the entire approach and begin once more anew. Again, I crafted a new article. I painstakingly brainstormed a new approach, researched out the various points, and narrated it in a seamlessly smooth way.

But just as before, it didn’t meet the reviewer’s approval. Finally, I put the article on hold for a week. A couple of weeks later, the entire project was canceled.

At first I was stunned. I’d put at least two weeks worth of time into this article, and I thought at least some version of it was good enough, or salvageable, to avoid a fate in a content scrapyard.

Why had the entire project been canceled? This initial article was supposed to kick off a series of articles that would run throughout the year.

The effort was not worth the payoff, I was told. The hits we would receive from the article’s publication didn’t seem worth the time to write, review, and approve the content, especially with all the directors and leaders involved.

Although shocked, I also felt a sense of relief. I no longer had to do the project. There were a lot of other projects I could focus on instead. I could put this impossible article — and all those that would surely follow — completely out of my mind. Except I couldn’t entirely do that, for some reason.

For nearly a month I focused on other matters, but every now and then I brooded on the failed article. It seemed misguided in a fundamental way, but how? What did I do wrong? I had confidence in the quality of my writing. The essay read well. The problem, perhaps, was the initial assumption. We assumed that an article that takes a week to write should get a significant amount of visibility for the cost involved. If that visibility can’t be ensured, the article isn’t worth writing. Was that assumption correct?

It may be true to an extent. But it seemed like an easy approach to visibility, trying to leverage an existing platform that already had a sizeable readership. In today’s publishing, destination doesn’t matter as much anymore. Good content gets retweeted, blogged about, and shared on enough sites that the original URL isn’t all that significant.

But even more problematic is the idea that you can simply get instant visibility. If there’s one thing I’ve learned about blog readership, it’s that it takes time to grow an audience. There’s hardly a way to instantly grow your readership. Sure you may have a home run post that doubles or triples your existing readership, but in my experience, subscribers grow slowly and steadily. I add about 50 readers to my site a month. Each good post brings in about 15 new readers, while several leave as well. It’s slow going, and it takes a lot of time and patience. To think the whole effort isn’t worth it because it simply takes too much time for the payoff is thinking only in the short-term.

But how do you convince someone that the site may not achieve the visibility we want for at least three years, and that during that time, we’ll need to publish several high quality posts a week? Online publishing isn’t an overnight sensation that erupts when you write one or two engaging posts. You have to write solid content over a period of years to build up the readership you want.

Despite my misgivings about the cancellation, the project was never resurrected. I instead fueled my efforts into another site that had a much smaller readership, and I wrote or edited article after article for that site. I no longer ghost-wrote anything. I simply wrote, and managed other writers and their writing. About 8 months passed by like this, writing and publishing at a steady pace of about 2 to 3 articles a week.

I am not sure that corporate business leaders have the patience and stamina to build up a loyal following of readers. It’s a long, slow, calculating process that cannot be won with a single post. That introductory post I labored over for weeks — it was just one nail in the framework for a house. Blogging requires steady content, week after week, persuading one reader at a time, one word at a time, that your site is worth reading, following, and sharing. Is any single article so important that it deserves endless scrutiny and revision before publishing? Perhaps instead what we need is writing and publishing endurance, the ability to keep going week after week, constantly seeking out the right content for the audience, and crafting it so that readers find it appealing.

Failed articles shouldn’t be a sore point. In the history of writing, how many countless articles have been written and never published? As a professional writer, I’ve developed thick enough skin that discarding weeks worth of effort shouldn’t upset me, nor undermine my self-confidence. Still, the way the discarded article keeps creeping into my psyche, returning again and again in unexpected hours, means I left something unresolved.

I still have the essay sitting on my hard-drive — about a dozen versions of it. I can’t put the article to rest in my mind, but rather continue to contemplate and reflect on it, like an unsolved mystery. A cold case that keeps stewing. It doesn’t want to die, I think.

I just re-read that essay I wrote months ago. Was my memory playing tricks on me? Was it really something that should have been discarded? All my literary judgment tells me no. It is as smooth and flawless as the day I wrote it.

Was there some element that needs discarding, some small line or paragraph that is poisoning the whole? Perhaps, but like a paring knife to a spot on a bad apple, I am confident I can carve it out.

It’s developed a life of its own now, and won’t be silenced.

Sooner or later, I am going to publish that darn essay.

————

photo by mishari, flickr

Blog Sponsors

• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree

Author-it Aspect

My colleagues and I were talking the other day about where we’re going to publish some help content. The scenario we’re addressing is a project that will be translated into 38 separate languages. Additionally, there are 28 roles for the system. This means there would potentially be 1,064 outputs (38 x 28), assuming help is to be specific to each user’s language and role. This is a tremendous amount of material to generate and keep track of, and the thought of it overwhelms me.

We’re implementing Author-it in my organization, and one of the technical leads showed us Author-it Aspect. Apparently this tool would allow us to publish all the content in the same output. Then through the user’s profile, he or she would see the help material that is relevant to his or her role and language. Rather than 1064 outputs, we’d have just one.

Here’s the demo that my colleague showed us. It’s a recorded webinar that I’m reposting here with Author-it’s permission.

This is the demo of Author-it Aspect. Watch about the first 5 min.

You’ll see that you can select options to see different views into the content. My understanding is that through an Author-it Aspect API, you can configure the views to your user’s profile (assuming the user logs in). Otherwise, if not logged in, the user would select the view from the Options menu. But here’s the point: it’s all the same help file. There aren’t hundreds of different help outputs to coordinate behind the scenes.

This seems like much needed technology that would simplify a lot of robust publishing situations. Granted, I think Aspect requires its own server and is somewhat costly, but the time it would save in managing the content might be worth it. Is anyone out there using Author-it Aspect? I’d love to hear about your experience.

For more information, see Author-it Aspect.

8/26 update: I recently learned that Aspect doesn’t support multiple languages as variants. This functionality won’t be available until version 6.0 of Author-it is released (within a few months).

Blog Sponsors

• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree

Part of the reason we’re doing more user awareness is because we’ve suddenly published dozens of new websites, tools, and other technical solutions, and we’re trying to help the general membership come up to speed with what’s new.

As a strategy for user awareness, some leaders made a list of topics they want me to emphasize in regular web articles over the coming year. In determining a cost/time estimate, I’ve decided to account for post-publishing time as well, since merely publishing articles no longer addresses the whole time involved in writing.

The time involved in writing an article or a post depends on how many comments and responses you get from readers. After you publish an article and send the link across Twitter, Facebook, and other channels, comments start to pour in. Users may respond in comments below the article (if you have a comments feature), or they may respond on Twitter, Facebook, forums, email messages, in their own blog posts, and other ways. It’s the writer’s responsibility to respond to feedback where necessary.

Sometimes the post-publishing word count is actually longer than the pre-publishing word count. For example, my post on the enterprise help authoring problem was about 500 words long. However, the post received more than 30 comments. I responded to many of these comments. The total word count of just my own responses was about 1,800 words — more than three times the length of the original post! In this case, the bulk of the writing for the post came in the post-publishing phase.

Pre- and post-publishing word count -- sometimes the post-publishing word count is a lot higher.

Granted, making a comment doesn’t often require the same effort as writing the original article, but there is still time involved. The number of responses required also depends on how I comment. Sometimes my comments elicit new responses from readers (it’s a conversation, remember), so the response length can increase even more.

Twitter and Facebook Conversations

Conversations also take place over Twitter and Facebook. For example, last week I published an article about a crowdsourcing site my organization created. I included the #lds hashtag on the tweet, and as a result, the tweet was retweeted 20 times, with a total reach of about 6,600 people according to Tweetreach.

An article also has a conversation taking place on Twitter

Tweetreach lists all the people who mentioned the article. It would be good to at least read these retweets to see if the readers have questions or responses or other comments on the article. Many people on Twitter simply retweet the link, which doesn’t require a response. But a good social media strategy would probably have me follow the people who retweet the content, or at least take note of the Twitter audience. The same applies to Facebook.

My basic point is that the time estimate for writing should include both pre-publishing time and post-publishing time. I’ve written similarly how technical writers should not consider a help file complete when it’s initially published. Help is in a state of perpetual beta — you’re always improving the information as questions, problems, bugs, and other issues come to light.

Worth the Effort?

One problem with this heavy post-publishing model is that responding to comments often constitutes a one-to-one effort, whereas writing the article is a one-to-many effort. The payoff for writing the article affects 80 percent of the users, whereas the payoff for responding to comments only affects about 20 percent of the users. At some point, you may be expending a lot of effort responding to individual comments without having much payoff for that time. Because of this, it’s probably best to not spend time responding to every comment — just the ones that seem to need a response.

Real Time Approval?

Another aspect to consider with the post-publishing word count is approval. When writing content in a corporation, much of this content has to go through several approval processes before it’s published. For example, you may need approval from the product manager, the communications director, the intellectual property department, and the website owner before publishing. The original article is highly scrutinized.

But what about approval processes for the post-published content? Remember this content may be three times as long as the original article. Should each of these comments go through approval as well?

Post-publishing activities in social media channels cannot go through the same approval processes because there’s an entirely different dynamic and time constraint on the content. Conversations take place in near real-time. Companies should just assume some risk by allowing writers to respond with their own judgment on articles. The risk of a poor comment is lower than the risk of not responding at all (or not responding in a timely way). I’ll probably address real-time engagement in a future post.

Overall, not a lot has been written about post-publishing process and efforts, but this is an area that deserves more attention.

Blog Sponsors

• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree

And yet, I regularly need to update the help after the application is released. For example, in the previous project I was writing about, the Local Unit Calendar, after release I learned about a bug in production. I received a couple of questions from a user, and the answers weren’t in the help. I had an error in the section about changing calendar color. And I needed to add some more instruction in another section.

When I explain to system engineers that I need a server for my help that I can update on the fly, they always ask why. Why can’t I just include my help content in the application? However I explain it, the reasoning always comes off sounding like an excuse for not being able to finish my work on time for release.

And yet, I sometimes don’t find out about an application until two weeks before the application goes live and needs documentation. Although I need to create video tutorials, the interface isn’t frozen until the application goes into hardening and becomes a potential release candidate.

If the materials need to be translated, the Translation department requires at least a month of turnaround time. If the content will be printed and sent out to users, I may have to get the content approved from a department that ensures message consistency.

If subject matter experts don’t take time to carefully review the material and video scripts before release, there’s a good chance the help will contain some inaccuracies. Project managers and quality assurance engineers rarely have time to review help material the week before a release. If I don’t submit the help content to peers for a style review, there’s a possibility that typos or inappropriate formatting will also sneak through.

In short, there’s a host of reasons why the documentation might need to be updated after the application is released. If I could access the help content and continue to add and adjust it at any time, independent of application releases, it makes documentation less of a time crunch the night before (for example, to finish the video tutorials for the calendar app., I stayed up until 5 a.m. the night before).

The concept of having control over your help content, to update it at any time, is what I’m calling content independence. Establishing content independence in your publishing environment may be a battle that can take years. For example, at a previous job, it took five years to finally convince architecture that we needed and deserved our own independent folder on a production server.

In my current situation, I’ve pursued publishing routes in infrastructure that would enable on-the-fly updating, but for two years in a row I’ve come up empty-handed. With wikis, I think I’ve finally found the holy grail of content independence.

By nature, wikis sidestep the problem of file transfers, because you can always immediately access and update the content through the browser interface. For content outside the interface, such as PDFs, SWF files, or diagrams, which you can’t code into wiki syntax, you can still upload the video tutorials through Mediawiki’s file upload utility (and probably through a lot of other wiki interfaces as well).

Mediawiki's file upload utility

The interface file upload utility gives you a tunnel to production without having to go through change release!

Note: You can’t upload every type of file through Mediawiki. HTML files and Javascript files, for example, are usually forbidden file types. Also, the file upload is one at a time, so a traditional webhelp system generated by Flare or RoboHelp wouldn’t be uploadable through a wiki’s file upload utility. But if you’re using a wiki for documentation rather than a static help authoring tool, this isn’t an issue anyway.

To enable file uploads in Mediawiki, you have to make a few tweaks to your localsettings.php file. You may have to adjust your settings in the php.ini file too. And if you want to embed your videos, you may want to install a Flash extension. I’ll include instructions for doing all this in another post. But basically, despite the drawbacks that wikis involve, they provide you with an invaluable advantage in help authoring: content independence.

Blog Sponsors

• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree

Also, most of the traffic seems to come during work hours. This tells me that my audience considers my blog somehow related to their work (that, or a welcome distraction from work). One insight Lorelle says is that you should publish before the moments of highest traffic on your site, similar to preparing a dinner table with food ready to eat before the guests arrive. Nice analogy.

I also find that I’m more comfortable publishing during off-work hours, because I don’t want people to think I’m blogging at work, even if I’ve already told my manager that I schedule posts to publish at specific timestamps. Thanks Anne Gentle for the link.

Blog Sponsors

• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree

In this podcast, I talk with Richard Hamilton about his new publishing imprint, XML Press. Richard started XML Press to serve the needs of technical communicators, publishing books on topics that may not get traction from large publishing houses due to the limited audience, but which perfectly fit a smaller, niche technical communication audience. Focusing on practical topics that technical communicators can use to improve their jobs, XML Press already has one book available and two forthcoming:

• Managing Writers: A Real World Guide to Managing Technical Documentation, by Richard Hamilton
• Wiki: Grow Your Own for Fun and Profit, by Alan J. Porter (coming soon)
• Conversation and Community: The Social Web for Documentation, by Ann Gentle (coming soon)

Richard is looking for topics related to technical communication and XML. If you’re looking to write a book on technical communication, be sure to check out XML Press. Richard also has a blog called Managing Writers.

Blog Sponsors

• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree

Blog Sponsors

• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree