That’s what you’re doing when you write documentation, marketing collateral, Web content, articles, or whatever your deliverable is. Freelance writer Bruce Byfield examines this in detail in a post on his blog. Admittedly, Byfield is talking about general non fiction or even fiction writing, but the lessons he imparts in that post can be applied to technical communication as well.
Byfield writes the following about his initial experience as a writing teacher:
When I first stepped in front of a class, I imagined that I fully controlled the experience. As a result, my first semester teaching post-secondary was almost my last. I needed to learn that, while some students wanted to learn, I needed to cajole or entertain others before they would even try to absorb my lesson.
Substitute readers or users for students and you probably understand fully what Byfield is getting at. The people reading your material want to learn — about your company’s products and services, about how to use those products, about how to quickly solve the problems that they encounter.
With documentation, you can collaborate with the user on two levels:
- By giving users what they want in they way they want it. This could, for example, enable users to remix content to suit their own needs.
- Initiating a conversation with users, and incorporting user-generated documentation, comments, and suggestions into your content. This could be tricky as far as copyright and licensing go, but you could do what Splunk does and use a Creative Commons license for all community content.
How do you currently, or plan to, collaborate with your readers? Or is this even in the cards for you? Feel free to leave a comment.
DITA is becoming very serious business. There’s now a DITA Help subcommittee at OASIS. The purpose of the group is four-fold, but their most important goal in my opinion is to:
remove the obstacles to effective use of DITA for Help systems through the creation of best practice guidelines, cookbooks and worked examples, and to promote the use of DITA for creating Help systems and user assistance content
The group has already released several documents. The most intersting one (at least so far) is this one. While I’m not a huge fan of best practices (I’ve found that in multiple cases the best practices aren’t always best), the document does offer some good guidelines for creating online help with DITA. And the group uses DITA to create their documents, to boot.
No, I’m not venturing into the realm of age discrimination with this post. I’m talking about the content that’s made available to customers and vistors to your employer’s Web site. What got me thinking about this was a blog post that I recently read titled “Out of Date Content Should Be Deleted.”
While the post focuses on news stories on a Web site, the same thinking can be applied to documentation and technical collateral. I’ve seen corporate Web sites that contain docs for versions of applications that are several years old. But how much of that information is still relevant, and should it still be made publicly available?
My thought is no. I tend to advise the companies that I’m working with to only make the documentation for the last two releases of a product available on their Web sites. From what I’ve seen, the larger number of customers will be using or have upgraded to one of those versions when the latest edition of an application is released.
Older documentation should be archived, but in an easy-to-find location in case a customer needs it. All you have to do is dig into the archive and send it off.
What are your thoughts on this? Feel free to leave a comment.
After a lengthy hiatus, the podcast is back. Recently, Aaron and I had the pleasure of talking with Anne Gentle about wikis, the OLPC project, documenting Open Source, and more. It’s an interesting way to spend about 47 minutes of your time.
You can listen to the podcast here, or use the player below.
Presentations are slowly becoming more and more a part of the professional life of DMN Communications. Aaron and I have found that we enjoy presentations — both giving them and the process or creating them.
I’ll be giving a presentation next month at DocTrain East 2008. Usually, the process that Aaron and I use to develop a presentation is:
- Create an outline
- Write the script for the presentation
- Build the slides
This time around, I took a different approach — I built the slides and am writing the script around the slides. In essence, I’m building the story around the images in the slides.
Strangely enough, the process has been working. Using the outlines and the slides I’ve been able to write a pretty good script. I’m still in the process of refining it, but the results are better than I expected.
The problem I had was creating the slides. I don’t like slideuments, and tend to follow the advice of presentation guru Garr Reynolds. I’m not the most visual person, and finding the right images was a bit of a challenge.
I’ll know on October 31st whether or not this process was successful. Check this space around that time for either a success story or a lament on screwing up.
Do you give presentations? If so, what’s you’re process? Feel free to leave a comment.