Tag: documentation

Categories
Blogroll Business Captivate Language Marketing Process Rants Uncategorized Useful Links Water Cooler Stuff Writing

Agile Development and Technical Writing

For additional information regarding Waterfall/Agile development and how it impacts technical writing, please refer to previous blog posts written by Eric Sedor and Shaun Kelly.

Moving a product out the door to capitalize on market demand is a necessity – it’s simple economics! Consumers demand constant product improvements. This “out with the old, in with the new” mentality has led many successful companies to switch from Waterfall development  to Agile. What does this mean exactly? For the uninitiated, use this simple analogy. Waterfall development can be compared to a marathon. All software features are built in one long process and then errors are fixed. Agile development is more like a series of sprints. Software is released in a series of small iterations. Each release includes a few added features, and errors are corrected along the way rather than at the end. As you can imagine, the switch to Agile development completely shatters the status quo and roles of people associated with the development teams. This led us to wonder: Specifically, how does the switch to Agile impact the role of technical writers?

Continue reading “Agile Development and Technical Writing”
Categories
Blogroll Business Marketing Networking Process Training Uncategorized Water Cooler Stuff Writing

The Three Basic Elements of Technical Communication

When clients tell me that they can write their own user manuals because, after all, they say, they already know how to write, I’m reminded of a quip from an old friend, frustrated by his software developers’ inability to complete a payment application on time: “Why does it take so long? It’s just typing.” Sadly, I sometimes think, people think the same about technical writing: It’s just typing. Which got me thinking: What does a good technical writer have to know to be a good, dare I say, great technical writer?

Continue reading “The Three Basic Elements of Technical Communication”
Categories
Blogroll Business Captivate Flare Humor? Language Marketing Networking Rants Uncategorized Water Cooler Stuff Writing

Corporate Speak: Between Sweet Spot and Wheel House

These days, business speak surrounds us. It doesn’t discriminate against company size or position status. College interns and CEOs alike find themselves dropping buzz words in conversation. But to what end? When is enough, enough? The next time you want to move forward, deliver, or buy-in by all means go for it. But don’t expect people to know what you’re talking about. The more time your employees spend guessing the meaning behind your jargon, the less productive they are. Ben Franklin sums it up best:  “Time is money.”

Continue reading “Corporate Speak: Between Sweet Spot and Wheel House”
Categories
Blogroll Flare Language Process Rants Uncategorized Writing

Why is Technical Writing so Difficult?

Technical writers are a rare breed. To be successful in this profession, you have to be patient, know how to communicate, and, last but not least, understand technical concepts. These tough demands have been the inspiration for this article, the third and final, in what we like to call our technical writing “rant topics.” See the first two in the triptych, “What’s Wrong with the Passive Voice” and “Why is Consistency Important.”

So, what makes technical writing such a challenge?    

Continue reading “Why is Technical Writing so Difficult?”
Categories
Captivate Language Process Rants Uncategorized Writing

Why is Consistency Important?

It’s not like technical writing isn’t already incredibly boring, so why does it have to be consistent? Such is the typical complaint about what we at Shoap do to earn a living. So how important is consistency?

While we sometimes fantasize about people grabbing one of our documents and cozying up to the fire to spend some quiet hours learning how to use a new piece of hardware or software, the reality is starkly different. As they used to say about Ivory soap, 99.44% of the time the only reason people crack a user guide or click on online help is because they’re stuck: they can’t figure out how to do something that they need to do – and need to do immediately. 

Consistency means you can find information quickly and understand that information when you encounter problems. Let’s see how.

Continue reading “Why is Consistency Important?”
Categories
Business Captivate E-mail Language Rants Tools Uncategorized Writing

What’s Wrong with the Passive Voice?

Why do people use the passive voice? Engineers, scholars and business people alike use the passive voice on a daily basis – probably without even realizing it. So then, why is passive voice frowned upon and what exactly is it?

Simply put, passive voice is a style of writing that makes the object of the sentence the subject of the sentence. Sentences written in passive voice are structured so that the noun who performs the action is not the subject. Confused? Consider this illustration.

Sentence 1: I made a mistake (Active)
Sentence 2: Mistakes were made. (Passive)

Continue reading “What’s Wrong with the Passive Voice?”
Categories
Business Marketing Process ROI Tools Uncategorized Writing

RFP Nightmares. Had Enough?

In an earlier article (http://www.shoap.com/rfp-responses-go-technical), we discussed the importance of responding to RFPs with correct, easy to read and understand responses. Several of our readers wondered if there were any tools that could help them address the arduous task of responding to RFPs. This article is for them.

Unquestionably, there are more onerous tasks than responding to a big, fat request for proposal (RFP). Unfortunately, I just can’t think of anything. People who have to do this for a living spend countless (and thankless) hours, ensuring the response is correct and flawless. These responses can go for hundreds of pages, require inputs from various and sundry departments within the organization, and are under tremendous time constraints. It’s stressful just thinking about it. Many companies, however, are facing this nightmare head-on by investing in software that automates the process. Leave the copy/paste method behind.

Continue reading “RFP Nightmares. Had Enough?”
Categories
Business Language Marketing Training Uncategorized Water Cooler Stuff Writing

Another Technical Writing Success Story by Mark Ellingson

After an eighteen year career in technology, I have one thing in common with many of my colleagues: we have children. Eating lunch or grabbing a coffee I am frequently asked “What should my child do to get a job in technology” and “What did you major in?” and “I heard about a computer camp where kids make games. Is this a good idea?”

Continue reading “Another Technical Writing Success Story by Mark Ellingson”
Categories
Language Process Tools Training Uncategorized Writing

See, Technical Writing Is Good for Something by Robert Pudlik

I have little recollection of how I decided to become a technical writer. I’m not even sure how I found out that technical writing was a thing people did. I followed some roommates from college to Atlanta from Connecticut in the fall of 1993. I was a pretty good writer and I had always been a “computer nerd.” Today that might conjure up visions of Red Bull fueled hackathons. When I was growing up it meant reading operating system manuals. For fun.

Continue reading “See, Technical Writing Is Good for Something by Robert Pudlik”
Categories
Computer Languages Language Training Uncategorized

How the Audience Affects Technical Communication

Paul Clifton is a Ph.D. student in Digital Media at the Georgia Institute of Technology. He has been an on and off technical writer with Shoap Technical Services since 2007 and is currently working in interaction and user experience design at Intel.

Recently, I helped my friend update his resume. I’d helped him make a brand new one a few years before, and it had been an extremely painful process, so when he asked me to help update it, I nearly just said no. To my surprise, the draft he sent me proved that he had been paying attention when I had originally explained the rules for making a good resume, why they were the rules, and why following them mattered. His grammar and spelling still weren’t very good, but grammar and spelling are the easy part. Clearly communicating complex information by meeting the expectations of the reader is the hard part, and I was happy to see that he had pretty well taken care of that.

Continue reading “How the Audience Affects Technical Communication”