Four More Reasons Your Company Needs Technical Communicators

A few months ago I posted seven reasons an organization needs technical communicators. This week, a program manager I work with provided a few more ways that technical writers provide value to organizations and projects, so I wanted to pass along his wisdom—with my own discussion, of course. Because I gave seven reasons before, I’ll start with number eight.

Gryphon Mountain (2008). Articles>TC

Seven Reasons Your Company Needs a Technical Communicator

If you're in the business of developing and selling products that are in any way technical in nature, you probably spend most of your time planning or implementing specifications, development and release schedules, budgets, and engineering strategies. Or you may be directly involved in the day-to-day development and testing of the product. Whatever your role, the product is the most important thing.

Gryphon Mountain (2008). Articles>TC

How a Teacher Reminded Me Why I’m a Writer

I enjoy creating content. I like to take words and arrange them to convey ideas, paint pictures, spur thought, and give guidance. I like thinking about what arrangement of the words will bring the best impact. I write not necessarily because the world turns on ideas or because information is a buyable product, but because words have a lasting effect on people.

Gryphon Mountain (2008). Articles>Writing>Education>Technical Writing

Results of a Study about Online Experience

Users’ “enjoyment” of a site is tied closely to how easily they can find the information they want and stay oriented at the same time. I think this is a given for technical communicators; we know that users want to get answers as fast as possible, and documentation must be navigable.

Gryphon Mountain (2008). Articles>Web Design>User Experience>User Centered Design

Usability and Maintainability: Navigable Information

This post is part of a series on usability and maintainability. At first, meeting the needs of content consumers through usability can seem at odds with meeting needs of technical communicators through maintainability. My purpose in these posts is to discuss how technical communication best practices can satisfy both needs. I’ll use Gurak and Lannon’s usability criteria of users being able to “find what they need, understand the language, follow the instructions, and read the graphics.”

Gryphon Mountain (2008). Articles>Web Design>Information Design>Usability

Usability and Maintainability Not So Incompatible

A few days ago, I posted some thoughts I was having about usability and maintainability. On the surface, they seemed to be two ideas that couldn’t exist together. As I’ve thought further on it, I’ve decided that there may be situations (such as an example I gave in the first post) where this is the case. But on the other hand, the two can go together quite comfortably.

Gryphon Mountain (2008). Articles>Web Design>Usability

Important Players in the Content Review Game

One of the things that makes quality documentation on a product is a review process. I think many technical communicators would agree with me, however, that sometimes the process becomes more cumbersome than beneficial. The more people involved, the harder it is to meet deadlines.

Gryphon Mountain (2008). Articles>Documentation>Collaboration

Giving the Instructions a Fair Shot

We as technical communicators ought to afford each other the courtesy of using each other’s materials when the need arises. As the writers, we know how valuable it can be, and if we don’t use it when the need arises, we’re contributing to the prevalent concept that “no one reads it anyway.” By doing so, we shoot our own profession in the foot.

Gryphon Mountain (2008). Articles>Documentation>Technical Writing

Informal Help via Electronic Conversation Can Lack a Certain Professional Quality

Much documentation and training is delivered in one direction—the writer provides content, and the user consumes it. Perhaps this is one reason that technical communicators are looking for ways to create a conversation. It’s easier to address user problems when you can ask follow-up questions and get details. In a one-way delivery, you have to hope that what you provide will cover what’s needed. In a conversation, you can constantly get more information and react accordingly. Still, in an instant message, chat, or forum conversation, it can be hard to be clear.

Gryphon Mountain (2009). Articles>Documentation>Wikis>Social Networking

Blogging: A Way to Give a Bit More Meaning to Life

I’ve realized that having a blog helps me think more about my professional activities and interactions than I would otherwise. I give them more thought because I think about whether they’re something I can write about.

Gryphon Mountain (2009). Articles>Writing>Technical Writing>Blogging

“Good Enough” Really Isn’t

I’m enough of a perfectionist that I mentally wince every time I find myself thinking, “It’s good enough.” It sounds like a cop-out. It sounds like avoidance of responsibility and ownership. It sounds like I’m indifferent.

Gryphon Mountain (2009). Articles>Documentation>Quality>Technical Writing

Quick Reference Guides: Short and Sweet Technical Documentation  

Users often want documentation in a format that will give them the basics and get them on their way as fast as possible. Quick reference guides provide a short version of a manual, condensed from dozens or hundreds of pages down to just one double-sided sheet of paper. Despite the brevity of quick reference material, the thought process involved in creating, organizing, and laying out the content is time consuming. The format requires you to assess the content and decide the most important information the user needs to know. You must describe with extreme concision and clarity processes that usually require dozens of pages to explain. This article provides an overview of the strategies, tips, challenges, and benefits we have learned in using quick reference guides for our documentation projects.

Johnson, Tom H. and Benjamin Minson. Gryphon Mountain (2009). Articles>Documentation>Technical Writing

Small Ways to Convey Doc Accuracy

In this Web 2.0, connectedness-driven world, we acknowledge that to some extent, people seek out the most up-to-date information. If it was published in 2008, it’s ancient history. If it was published last month, it’s not as bad, but still not optimal. I think time stamps and version numbers are probably sufficient to suggest accuracy and “up-to-dateness.” What do you think?

Minson, Benjamin. Gryphon Mountain (2009). Articles>Documentation

Reveal Bugs in Release Notes, Not User Guides

Really, I think documenting the software the way it works with bugs is making more work for myself, so that’s probably the main reason I avoid it. I’ve got enough to do without changing the doucmentation whenever a bug is fixed. Release notes are easier—a much smaller deliverable whose focus is what’s changed and what’s still not quite right.

Minson, Benjamin. Gryphon Mountain (2009). Articles>Documentation>Technical Writing

Visualization Can Help Improve Writing

This exercise of increasing diagrams and illustrations to assist visual learners could potentially help me increase the clarity of the text in any deliverable so that it benefits any who take the time to read or at least scan. At the very least, asking myself whether I could easily illustrate or visualize the text may help me write more clearly.

Minson, Benjamin. Gryphon Mountain (2009). Articles>Writing>Rhetoric>Visual Rhetoric

Keys to Being a Trusted Source of Information

The issue of building trust with the audience is core to technical communication. If the user doesn’t trust your instruction, it’s worthless—no matter how well researched, thought out, and reviewed it is and how much time, effort, or problems it will save.

Minson, Benjamin. Gryphon Mountain (2009). Articles>Web Design>Rhetoric

Realistic But Hypothetical Examples

One of the reasons that technical communicators ought to know the business processes of their users (or at least the reasons they’re using the product) is to generate effective examples in the documentation.

Minson, Benjamin. Gryphon Mountain (2009). Articles>Writing>Technical Writing>User Centered Design

Consistency Leads to Trust in Information Sources

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.

Minson, Benjamin. Gryphon Mountain (2009). Articles>Writing>Rhetoric

Get Passionate about Technical Communication

Introverted people aren’t normally considered passionate. Even if you’re an extrovert, would you consider yourself passionate about technical communication?

Minson, Benjamin. Gryphon Mountain (2009). Articles>TC>Professionalism

Intellectual Property and the Not-So-Free Web

When you think of the free Web in the context of not having to pay for something, remember that there’s another aspect: Nearly everything that’s on the Web belongs to someone. And because the Web is so widely accessible, it’s entirely possible that if you abuse someone’s rights regarding their intellectual property, they will discover it and exercise their rights.

Minson, Benjamin. Gryphon Mountain (2009). Articles>Intellectual Property>Copyright

Why Technical Communicators Should Help with Product Text

A huge problem for projects is the lack of a common language between the developers and the users. When my colleague and I were preparing a presentation for an internal conference on this subject, he said something that has stuck with me. He said, “The goal of the project is to make the user successful.” I added to that: It’s not to write code or validate code. It’s not even to ship a product or make money (of course, this last one is especially true in a non-profit organization). At least, it shouldn’t be these things.

Minson, Benjamin. Gryphon Mountain (2009). Articles>TC>Technical Writing>User Experience

STC: Help the Communities Provide Value

Much has been said about the problem the Society for Technical Communication has found itself in, including on blogs, Twitter, and email listservs. I’ve deliberately kept quiet here until I had some semblance of perspective to offer. But I’ve come to the conclusion that maybe this is a crisis STC needed—an impetus to get us all thinking together about how to improve the model, how to offer more direct benefits to the members.

Minson, Benjamin. Gryphon Mountain (2009). Articles>TC>Community Building>STC

Why I Wasn’t Sold on Single Sourcing (and Why I’m Changing My Mind) 

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. But I’m changing my mind about single sourcing content. It’s about serving up different combinations of information to meet different audiences’ needs.

Minson, Benjamin. Gryphon Mountain (2009). Articles>Single Sourcing

The Reason I Haven’t Embraced Single Sourcing 

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.

Minson, Benjamin. Gryphon Mountain (2008). Articles>Single Sourcing

An XML Experiment Fizzles 

I did an experiment on Friday that taught me an important lesson: When it comes to handling XML structures, I know pretty much jack. This may be a fatal admission for a technical communicator, but it’s an honest one.

Minson, Benjamin. Gryphon Mountain (2009). Articles>Information Design>XML