Technical Writing, Documentation, and Training

404-873-4288

Our Blog

Expert tips, advice, opinions, and viewpoints.

“Waterfall is dead, long live Agile,” many voices cry, heralding a transition in the software industry from heavyweight engineering efforts to an almost sports-like scrimmage. Waterfall didn’tkeep up, they complain. Projects turned into congested pipelines and out of desperation to reclaim fluidity, the entire cycle broke down into an environment of iterative re-development that gave birth to Agile. Increasingly, developers collaborate in short sprints to rapidly address evolving concerns rather than as construction crews working from blueprints. What does this new era mean for technical writing as part of software development? More specifically, what is expected of an Agile Technical Writer?
Continue reading

eBooks

At some point, you’ve probably developed documentation to attract clients, educate customers, or provide instruction on the products or services you offer. Considering the effort put into creating the material, as well as the pool of expertise behind it, you might think about re-working some of your content to produce a general release eBook.
Continue reading

Why Technical Writers Scroll

In a recent issue of the Shoap Technical Reader, I commented on my reaction to a usability test in which I had participated (“Why Technical Writers Are So Weird”). The test was for one of our writer’s web UI development classes. He created an application to create a response to an RFP. His observations can be found here: http://superawesomegood.com/2012/03/31/searchers-and-scrollers/.
Continue reading

What Is Gamification?

You may have heard the term “gamification” floating around and wondered, “What is that?” The answer: Gamification is the new buzz word representing the idea of incorporating gaming concepts and techniques into non-game activities in order to drive a desired behavior. Marketing campaigns can use game mechanics to drive customers to their websites, sales agents can participate in games to drive competition and increase sales, and in our industry, documentation and training groups can build game-like training materials to fully engage the learner.
Continue reading

How many words is a video worth?

Who doesn’t like videos? From the silliest ones on America’s Funniest Home Videos to how to cook a turkey (one of my personal favorites which I come back to every Thanksgiving), there’s a video for everything you ever thought you wanted to know about – and lots of things you didn’t. Due to the popularity of these videos, technical communication has seen its share of examples. When you’re stumped on how to post an expense in QuickBooks, for example, you only have to Google the question and wait the requisite 0.20 seconds for the 400,000,000 results. Continue reading

MS Paint can be very useful

I used to take Microsoft Paint for granted. I saw it every once in a while in the Accessories folder when I was looking for the Calculator or Notepad but never really used it. Then I starting using screen capture programs at work to take screenshots for user guides, manuals, online helps, etc. When I was on my personal computer, I had no idea how to take a screenshot without a fancy program, and then I finally remembered Paint. Since then, I’ve used it for screenshots, creating and editing pictures/photos, and testing.

Continue reading

The Costly Myths about Documentation

Technical writing is an often misunderstood (and too-often maligned) field. Those who believe the myths about technical writing may not see its value and therefore miss its bottom-line benefits. Let’s look at those myths and then you decide the truth about technical writing for yourself. Continue reading

Laptop Shopping for the Non-Native Speaker

Take a look at this picture of the keyboard on my Dell Studio 1558 laptop (shown above).  Notice anything odd?

Well, where’s Number Lock?  What happened to the numeric pad (usually shares keys with the 7, 8, 9, U, I, O, J, K, L and M)?  These keys are typically used to type alt code combinations for characters not represented in the English keyboard. A Spanish speaker like yours truly would use them to type the letter “ñ”, accented vowels, and the “upside-down” exclamation and question marks.

The first time I tried to use alt codes with the laptop I thought:  “I must be missing something. They must have come up with some hip new way to do it.”  But how?

It turns out that in their infinite wisdom, computer hardware OEMs have decided to start eliminating features that customers “don’t want” (specifically, the Number Lock and Scroll Lock keys) in order to replace them with things that we just can’t live without, like the Windows key, a disk ejection key, or a right-click menu key. Fortunately, my manufacturer’s support staff offered some ‘helpful’ alternatives like using the Character Map or changing my keyboard language anytime I wish to type a non-standard character.  Alternatively, they offered to return my ability to type accented characters in exchange for a ransom payment of $18.99 for a Targus USB numeric pad.

I still haven’t been able to decide if I’m more frustrated by the removal of a feature that I ‘don’t want,’ the support staff’s absurd ‘solutions’ to the problem that the removal of this feature has created, or the manufacturer’s complete lack of awareness of the message that it sends: “typing in any language other than English on your U.S.-market laptop will not be tolerated.”

So let this be a lesson: if you or your employees value the ability to type special characters quickly (whatever the reason may be), make sure you add the Number Lock Key to your list of features to consider for hardware purchases.  It doesn’t come standard anymore.

So what is technical writing?

It’s quite often that I’m confronted with one of the most typical questions of today: so what do you do? My reply is that I do marketing for a technical writing company. The inquirer’s response: “cool” or “what is technical writing?” and I’ve never really had a good answer. Continue reading

Do people need to read it for it to help?

Why do companies fail to see the value of documentation?  Simple answer: virtually no one reads it. While true, does this mean that the few people who do read it are the only ones who benefit from the information in the documentation?  The answer is a resounding No. Continue reading