I started my current job five years ago this week. Reaching the level of senior technical writer brings me to ask whether I’ve got the smarts to go along with the time I’ve clocked.

A Narrow View of Tech Comm

When I graduated from Utah State University two months before starting as an intern, I thought technical communication consisted mainly of writing manuals, help systems, and the occasional tutorial. I thought the main activities were writing and creating images for print or Web.

My definition of a technical writer didn’t differ much from most people’s if at all.

I hadn’t heard the terms CSS, single sourcing, structured authoring, DITA, social media, Agile, RSS, SEO, or content strategy. Some of these things were either relatively new or not dreamed of at that point.

I belonged to the student chapter of the Society for Technical Communication, but the chapter members mainly learned from each other. There was only so far we could go that way.

› Continue reading…

Bookmark It

Hide Sites

I mentioned in my last post that one of my technical writing colleagues showed the user education team a spreadsheet where he had taken types of information, such as concepts, tasks, and frequently asked questions and indicated what types of deliverables it made sense to use them in.

Historically, I haven’t been a big fan of single sourcing content because I hate it when the content of the manual is exactly the same as the online help. I particularly remember trying to learn the basics of FrameMaker 7.2 in college, only to find that the lack of answers in the online help was duplicated in the manual on the computer lab shelf. So I think experiences like that—where someone thought single sourcing meant the exact same content in different formats—soured me on the idea of single sourcing.

› Continue reading…

Bookmark It

Hide Sites

Tom Johnson and Paul Pehrson posted recently about our team design reviews. These have started to turn into what we might call project reviews. In our team meetings, we usually brief each other on what we’re working on. In these project reviews, a couple of team members will go into more detail about their projects.

Going beyond the design review idea, where we would demonstrate our deliverables and get feedback, we also talk about the challenges we’re facing and receive suggestions for managing those challenges.

› Continue reading…

Bookmark It

Hide Sites

As noted in a previous post, people can come to trust sources of information through the source’s consistency. In my mind, consistency suggests regularity and dependability or reliability.

Consistency of Content

I’ve had my doubts about single sourcing, but one of the clear advantages is not having to find all instances of a certain bit of content and make sure each one is updated the same way if something changes. This is one of the things that users notice quickly and that turn them off fastest: wrong and contradictory information. (My last post discussed in part how accuracy engenders trust.)

This also points to the importance of checking facts. It can be tempting to just be pretty sure that something is correct, especially if time is pressing. But what if it’s not correct? What if it ends up contradicting something else? Then I’ve failed.

Consistency and Structure

Of course, when we start talking consistency, we often think of our documents’ formatting. Consistency is important from the serial comma all the way up to the arrangement of information. If I were Sarah O’Keefe, this is where I would put in a plug for structured authoring. Even if you haven’t implemented a strict structure for your documents or aren’t authoring in XML, it’s beneficial to decide on regular sections or parts of a topic and then stick to that pattern.

› Continue reading…

Bookmark It

Hide Sites

When we were starting the process of hiring for the two positions we just filled, something one of the applicants said inspired me.

In either his cover letter or resume, he wrote that he had experience using snippets and other features of Flare to execute complex single sourcing. That has made me think about how I can do that in my latest project (using RoboHelp 7).

› Continue reading…

Bookmark It

Hide Sites

The Content Wrangler is featuring an article by Richard Hamilton entitled, “Content Reuse: Is it Harmful?” Hamilton questions the blanket statement that reuse will increase efficiency and says that minimizing reuse is a better approach than maximizing it. He states:

There are two main reasons for minimizing reuse:

1. Every time you reuse content, you give your users another place to look at when they search for that topic. If you have the same content in several different places, your users can end up jumping around among those places, trying to figure out which one they should use. Having one, authoritative place for any particular module will simplify their search and avoid confusion.
2. Even with highly structured methodologies, reuse is not free. When you reuse content, you need to take steps to be sure that content will work in multiple locations. This takes effort that might not need to be expended for content that is not reused.

Chunks of content needs context, and if you reuse content, you still need to make sure that the context makes sense. Hamilton suggests that the practice of providing content in one place and then linking to it (rather than reusing it) is often overlooked. Some great thoughts here and definitely worth a read.

Bookmark It

Hide Sites

I was out of town over the weekend, and I managed to post once. But I came back pretty far behind in my Google Reader. An April 21st post from Communications from DMN reminded me of an article I read in STC‘s Intercom magazine issue on DITA over the weekend.

I wrote a post on the subject of single sourcing recently with some of the same sentiments as the DMN post, but Scott made some other points that I agree with. Basically, don’t jump on the single sourcing bandwagon without thorough analysis, and at the end of the day, your content management methods are transparent to the consumer of your information. Single sourcing exists for the benefit of the writer, not the user, at least not directly. (You could argue that if the writer is working more efficiently, the user benefits.)

However, Sarah O’Keefe’s Intercom article, The Hidden Cost of DITA, did make me think about one pro of single sourcing: You have fewer places to update when you have to make changes. Currently, with a couple of ongoing development projects I’m on, when there’s a change to existing functionality, I have to think about the corresponding effects in the documentation. Due to the fact that the projects are ongoing, I’ve written the documentation recently enough that I can usually locate those places quickly. But what about later on, when my memory isn’t so fresh? Or when someone else has to take over maintenance of the material?

And so the discussion continues. But where I work, we tend to watch what’s happening in the industry and let the best practices come out on top rather than taking hold of something because it’s the rage. I think that’s a comfortable place to be. In the end, it’s probably the least expensive because we can carefully weigh pros and cons of switching our methods. If a craze passes before your analysis is done, you’ll probably be glad you took the time to do it. If the hype continues, there may be some substance behind it.

Bottom line is that switching to single sourcing schemas like DITA is not a decision to be made lightly. Remember, your users probably won’t know the difference if your strategy doesn’t affect your content.

Bookmark It

Hide Sites

The field of technical writing is making a push toward single-sourced content. This involves authoring in one place and being able to chuck the content into different formats, such as help systems and manuals. It’s supposed to make things better for content management, as well as for localization because you have only one set of content that has to be translated.

I personally haven’t bought off on this yet. For me, there’s one basic hang-up.

› Continue reading…

Bookmark It

Hide Sites