Can technical writing suck less

I agree with @mbakeranalecta that the purpose of tecnical writing is not to entertain but to inform.

I recall a textboook on software development that I had in college where the text was regularly interrupted with little stories about "Sally's first day as a programmer" and the like. These stories were presumably intended to liven up the text while illustrating poings from the chapter. Personally, they just made me feel embarassed for the author. The stories were not only mostly irrelevant, but lame and cloying. "Oh, how exciting it is to work in the real world of software development! Sally exclaimed." It was just dumb.

That said, I think it can be good to break the tedium of dry material now and then. I wrote a database book where I got a cartoonist to draw some cartoons for me that I THINK were not-stupid, maybe one for every chapter or two. I wrote a user's guide once where in the section describing how to add and delete users from the system, I introduced the section on how to restore a deleted user by saying, "If you delete a user, and then they come crawling begging for their old job back, you can restore the user by ..." Okay, not the sort of joke that will have people roaring with laughter, but I figured it was worth a chuckle and helped lighten the mood. I think that sort of thing is helpful.

But I would be very careful not to overdo this sort of thing. One little joke every ten pages can lighten the mood. Even if the jokes aren't very good, the reader probably won't mind. It's a break. But if you do it constantly, readers are eventually going to be saying, "Hey, I'm trying to learn how to operate a Foobar, not hear a bunch of your lame jokes."

posted about 8 years ago

CC BY-SA 3.0

Jay‭

1055 reputation 1 97 207 0

I think what you are missing is that all writing tells a story. Just because there is no love story or car chase, that does not mean your technical writing is not telling a story. You are just telling the story of hooking up a Chromecast. That is actually an exciting story for people who just got a Chromecast. They are your characters! Don’t diminish their excitement with crappy writing. Get excited along with them — we’re Chromecasting! — just as you would get excited along with a fictional character who is falling in love or having any adventure.

Get your head right, get into the story, and then write a personable, concise, helpful, plain language, understandable-by-all guide to Chromecasting that is a joy to read and use and that improves people’s lives by making their new Chromecast setup into a fun event with maybe a minor pitfall here and there that was easily solved, rather than a horrible chore that robbed them of hours of their precious life and then left them disappointed.

Instead of a fictional character waiting for you to tell them what to do, you have a community of real characters waiting for you to tell them what to do. You can make a million lives better with great writing. It is a serious responsibility and a great opportunity to grow as a writer and as a person.

posted about 8 years ago

CC BY-SA 3.0

Simon White‭

45 reputation 0 2 9 0

I would basically agree with the accepted answer that the main goal of technical writing is to assist someone in a task and it should focus on that. (Most of the time) you want to get a specific job done and fast. I would say most of that applies to online documentation that needs to be terse like short howtos or reference.

However I do disagree that this must apply to all technical documentation and that you must always restrict yourself to dryness. I see no harm in being informed and entertained (if possible).

I think there are several ways to put some fun into documentation.

• Use a good design that makes the docs easily readable and aesthetically pleasing
• Add images (and or videos) to visualize things
• The problem with humor is that not everyone appreciates it. But, if you know your audience well, I think there is no harm in a pun or comic once in a while if it fits, example: https://pbs.twimg.com/media/DldA_cIXgAADj5w.jpg
• Another example for terseness and fun to look are some technical sketchnotes. The technique can come in handy for cheat sheets
• Add analogies and images to explain things, Example: An introduction to HTTP/2 for SEOs

• Source: https://xkcd.com/293/
• License: https://xkcd.com/license.html

posted about 5 years ago

CC BY-SA 3.0

Sybille Peters‭

5 reputation 0 1 1 0

The number one thing that you have to realize about technical writing is that people do not read it for its own sake. They read it because they are trying to do something and they need more information. The writing does not need to engage or entertain because the reader is already engaged with the task. It is their engagement with the task and their need for information that drives them to read on, not their engagement with the text.

And for this reason, technical writing should not attempt to engage or to entertain. Anything you do in that area just gets in the way of what the reader wants: getting the information they need to get back to the job they were doing.

Plainness and clarity of instruction and description are therefore key virtues in technical communication. That should not make technical writing a dull job, though. Rather, it presents a different set of writing challenges.

Making ideas, concepts, and tasks plain and clear is a challenge in its own right. And because the reader is often coming to the documentation with false ideas about how things ought to work, there is a real challenge in how to engage them and their thought processes and how to put their feet on the right path, particularly because their attitude is "just tell me which button to push!"

Finally, remember that while in all other forms of writing your goal is to attract and keep the reader's attention, in technical writing the goal is to get them back to what they were doing as quickly as possible. The less time they spend reading and the more time they spend successfully doing, the better your technical writing is.

posted about 8 years ago

CC BY-SA 4.0

Mark Baker‭

4351 reputation 12 1104 742 58