When Tech Writers Don't Read Directions  

Find out what the Unspoken Rule of technical writers is and how to avoid violating it.

Minson, Benjamin. Intercom (2008). Articles>Documentation>Writing>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

What to Know When Switching from RoboHelp to Flare

I recently switched from RoboHelp 7 to Flare 5. I’m not the person to ask about the merits of one over the other because I don’t have enough experience with Flare yet. Because I’m coming to version 5 with my knowledge being only that which my colleagues have told or shown me, I hope to make life easier for anyone moving from RH to Flare or at least trying Flare out.

Minson, Benjamin. Communications from DMN (2009). Articles>Documentation>Adobe RoboHelp>Madcap Flare

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

Quick-Start Guides Require a Minimalist Mindset 

The point of a quick-start guide is, as the name says, to help the users get on their feet as fast as possible. This requires the writer to ask, “What is the absolute minimum that someone needs in order to get started?” The next best question is “What is the user going to do the most often?”

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

Five Skills for Managing Documentation Projects in an Agile Environment 

Sometimes, the Agile software development methodology seems like it could be renamed the “Fly by the Seat of Your Pants” methodology. But really, it means that you need a somewhat different set of project management skills for your documentation. I could certainly improve in these skills, but here are a few I rely on in an Agile environment.

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