Archive for the ‘Technical Writing’ Category

Best engineering flowchart, ever?

Monday, December 26th, 2011

The best engineering flow chart, ever? You judge.

Neil deGrasse Tyson thinks so, so I’m willing to consider it… however, there is no hammer. A hammer would clinch it. Or, a la Mythbusters, perhaps C4.


Image via Wikipedia

Speaking of Mythbusters… my wife and I sprung for the expensive tickets for this event in Sacramento on January 9th, 2012. Yes, there’s a live roadshow! Maybe I should’ve gotten seats further from the stage?

Enhanced by Zemanta

The joy of technical writing and web design

Tuesday, April 27th, 2010

The joy of technical writing, and of web design, is discovery, exploration, and mastery.

There are few businesses where one is always learning, not just how to do the basic work, but also about how the client’s businesses and their products actually work.

From nitty-gritty technical details (how does video get converted to an image on an array of LEDs?) but also, how does the client reach their customers? How do they brand their product? How do they get it out the door?

Technical writing is about translating the engineering details to the reader’s learning style, and delivering the critical ‘how-to’ information in a way that anchors to their pre-existing basis of understanding.

That’s relatively easy compared to modern website design, which is about translating the business details to the reader’s learning style and delivering the critical ‘why buy’ information in a way that anchors to their pre-existing basis of understanding, as well as their desires — All while executing the high-wire act of making it look good across a half-dozen browsers, and making it interact and flow in a predictable and pleasing manner… and considering how search engines will interpret the code, how the programming code works at a technical level, how the server works, and finally, how it should interact with several social networking sites, email systems, and lately, smart phones.

Regardless of whether the end result is a user manual, created in InDesign, delivered as a PDF, which will be printed and bound a thousand miles away and delivered with the product… or a web site, where the domain is pointed and suddenly the world can see your work… there’s that joy of creation.

Of finally pulling it all together into a coherent message. Mastering complexity.

It’s fun.

But, I’ll hire someone to do my taxes. You’ve got to draw the line somewhere.

Why Good Technical Writing is Good Marketing

Thursday, June 8th, 2006

We’ve all experienced the manual from hell.

You might have in your hands the greatest piece of software, the most fetishistic piece of hardware, or maybe just a kid’s toy with “some assembly required”.

But the experience is ruined because the manual makes no sense.

Is there an excuse? No, there’s not.

There was a time when manuals had to be written up on typewriters or longhand, they had to be sent to a typesetter, professional illustrators were brought in, proofing and correction cycles were long and painful… but the job got done.

Now it’s easy. Digital cameras, Technical illustration in PhotoShop, 3D rendering from CAD, great page layout tools like Adobe InDesign, Acrobat PDFs, for proofing and electronic distribution, printing plants worldwide that can take PDFs and produce manuals locally… Even translation is easier than it has ever been.

The problem is most acute in small and medium-sized manufacturing firms. To maintain full-time staff to deal with these things is often a substantial financial burden. Many such firms actually develop their products in countries other than their end markets… so the engineers don’t even speak or write the language of the end customer, or don’t do so natively.

With the web, you’d think there would be an ongoing dialogue between manufacturer and user. Sure, many companies post their support phone numbers, but few actually provide ongoing guidance online, and many that do, do so inadequately. The long wait for support with most companies is a pretty good indicator that they are spending in support what they didn’t spend in documentation.

So why is it still a last minute effort by a low ranking engineer with no grammar skills and a complete unwillingness to use spell check? Why is there no user-testing? Why do the online help, the print manual, and the PDF on the provided CD all have inconsistent, often contradictory, always incomplete information?

The answer may differ between organizations, but it really comes down to a lack of commitment to end users. Many organizations isolate themselves from their users, putting the burden on retailers or their support staff, after the sale. There’s a booming aftermarket for manuals and magazines for most software products. All are indicators of a failure to communicate.

If you recognize this problem in your organization and would like help resolving it, contact me.