Spring into Technical Writing 173
| Spring into Technical Writing for Engineers and Scientists | |
| author | Barry J. Rosenberg |
| pages | 318 (with an 18 page index) |
| publisher | Addison Wesley |
| rating | 9 out of 10 |
| reviewer | Simon P. Chappell |
| ISBN | 0131498630 |
| summary | Solid writing advice for technical folks. |
Who's it for?
The book's full title pretty much nails the intended audience; it is absolutely for engineers and scientists. Unlike most works on literary skills, this book treats you like a geek and realizes that you don't want to write prose, but you do want to communicate through a written medium. If you read Slashdot on a regular basis, know what Linux is or the majority of your books have diagrams, figures and tables instead of pictures, then you are a candidate for this book. If you can name more than one type of verb, then you may well be better sticking with your copy of The Elements of Style.
The "Spring into ..." series of books is based around the idea of transferring concepts quickly and efficiently. Barry, editor of the series as well as the author of this book, recounts his experience of a few years ago, when he had to learn a number of new skills quickly and could not find books that would meet that need. In his own words, "I didn't have time to become an instant expert, but I did have to become instantly competent."
The Structure
The book is split into four sections, each building upon the output generated in the previous section. The first section introduces the reader to the concept of technical writing, including how it varies from the other sorts, and then covers how to plan your documentation. Section two covers the actual writing. It starts with words, moves to sentences and progresses to paragraphs, before bringing in lists, tables and graphics. Section three looks at specific types of documents that are meaningful to engineers and scientists including manuals, web sites, proposals, lab reports, PowerPoint presentations and emails. The fourth section teaches basic editing skills, core concepts of typography and a discussion of practical punctuation.
Chunky, and I don't mean soup.
The series explains its topics in one or two page units that it calls chunks. The individual chunks in a chapter build on previous chunks. Delightfully, there are plenty of good examples throughout the book and each chunk has at least one example in it.
What's to like?
I found much to like about this book, and if any of these points ring true with you, then there's a good chance that you'll like it too. The first thing to note is hopefully obvious, and that is the quality of the writing. Or at least I'd hope that it would be obvious that the writing was excellent in a book about writing! There is an upbeat and cheerful tone that, even with a few corny jokes in the footnotes, doesn't cross the line into being either saccharine or condescending.
After the quality of the writing, the thoughtful division into chunks pretty much make the book for me. The information within the chunks is excellent, well indexed and easy to locate through the table of contents. The chunks cover task-sized activities; for example, you might wonder if a semicolon would work at a certain juncture. So you turn to chapter 20, the chapter on punctuation, and then to page 286, where a straightforward explanation of the correct usage of semicolons (with five good examples) awaits you.
While there are many depths to be explored in writing, this book stays close to the surface, giving enough help and guidance without turning the reader into an expert on composition. All advice is targeted for the concept, in the context of the likely circumstances that an engineer or scientist would need it.
The book stays on target all the way through. The stated audience of the book is engineers and scientists, and that remains the focus throughout. This makes a delightful change from books that claim to cover advanced topics, but start out trying to teach you the basics; Java books seem to be especially guilty of this.
The third section of the book covers many of the types of written material that a reader may be called upon to produce and not only gives examples, but it also shares tips and lessons learned from experience for each of the document types. Examples include pacing a PowerPoint presentation and writing a book proposal.
Oddly enough, for a book written about writing, for a technical audience, by a professional technical writer who also teaches occasionally at MIT, there is nothing to complain about in the writing department. So, switching to scraping the bottom of the barrel mode: I didn't like the ragged-right text justification and a few of the jokes were very corny. That's it.
Conclusion
This book does what it sets out to do, that is to equip engineers and scientists with the skills to communicate clearly and effectively through a written medium; whether that be a website, an email or a report. I recommend this book to everyone, from organizers to doers. Organizers like to write about what should be happening, and doers, while they may tend to shy away from writing, are often asked to write about what they've done for the organizers. This book covers that full circle.
You can purchase Spring into Technical Writing for Engineers and Scientists from bn.com. Slashdot welcomes readers' book reviews -- to see your own review here, read the book review guidelines, then visit the submission page.
Like a breath of fresh air (Score:5, Insightful)
Huh... (Score:4, Insightful)
Write it down and when you are gone we will speak nicely of you.
Re:Like a breath of fresh air (Score:5, Insightful)
One problem (Score:3, Insightful)
Re:Huh... (Score:5, Insightful)
Communication is not bureaucratic fluff (Score:3, Insightful)
Just b/c you get an "A" ... (Score:2, Insightful)
I am not saying you did not deserve your grade, but I am saying that good technical writing in context is not easy.
Rule#1: Respect your audience (Score:5, Insightful)
As a project manager, one of the greatest skills I can bring to the table is being able to communicate effectively with the technical people (TP) on my team, and then turn around and explain to the non-technical people (NTP) in our organization what the heck they were talking about, and why it's important. I'm able to do this, in large part, because I have respect for people on both sides of the equation, and take the time to understand what they're saying, and communicate in their terms.
Unfortunately, there is traditionally very little respect from either of these camps, going either way. As long as we TP assume that we're talking to PHB's, Boneheads, and Golden Parachute Weenies(tm), it's going to show in the way we write.
If instead, we presume NTP to be intelligent, with a different (but still valuable) skillset, and keep that mindset at the forefront, our consideration for their intelligence will come through and so will our message.
Here's a test. Take your last technical proposal, and consider how you would structure and word it for (insert name of close, non-technical relative such as Mom, Dad, etc.). Then, write it that way, but without the analogies to Mom's wonderful cooking, or Dad's "Viagra incident." I guarantee that if you respect the audience, and don't talk down to them, you will improve your writing and communication.
Add in the practical suggestions from a book like this, and you should be in good shape. However, neither one of these components is a substitute for the other.
Tim
Re:Communication is not bureaucratic fluff (Score:3, Insightful)
Re:Like a breath of fresh air (Score:2, Insightful)
On Writing Well [amazon.com] is another great book, though it's not exclusively about technical writing. It does, however, briefly cover it.
It's definitely worth a read. Or three, in my case.
Reverse engineering code is a waste of time (Score:3, Insightful)
I should NOT have to reverse engineer your code to find out what it does. A competent technical writer can take a well-written software specification and have a draft user manual ready by the time the code is compilable.
"On Writing Well" (Score:3, Insightful)
Just as programmers compliment the "elegance" of code, Zinsser's focus on writing with economy is a lesson more should follow.
What's the Point? (Score:3, Insightful)
Your time and their time is much better spent formulating some good process documents, so you can get busy herding them into producing functional specs, and getting them to review and to sign off on engineering requirement documents, and so on.
After all, nobody expects the tech writers to seriously produce good code, or the tech support people to go out there and do the marketing.
Re:One problem / Technical writing (Score:4, Insightful)
The very best technical writers I've known were highly skilled writers with a rare ability to take highly complex and technical subject matter and communicate that information in simple (but not simplistic) and clear terms at the level appropriate to their audience.
Their most common complaint was that management (typically with engineering backgrounds) in the R&D operations that they were part of discounted or denigrated their role and contributions to products, instead of regarding them as the skilled usability professionals they are.
I don't know how many serious usability issues and critical bugs have been detected and resolved as a result of the work of those technical writers.
At a technical content review for an alpha-stage product line I saw one operations director who defined good documentation by the numbering system. Because the technical content was flawless, the only criticism he could come up with was, "Where's the numbering? Everyone knows that good documentation has to have good numbering!"
He followed that up with some comment about being short-staffed for developers on the team and "helping" the docs specialist by tasking some developers to take on future technical writing tasks. In other words, he was trying to get his developers take over the technical writing tasks and get rid of the docs specialist altogether. The only reason he felt he could do this was because of the attitude that anyone can write, and any developer who can write can also write good technical documentation. Unfortunately that attitude tends to be typical of many engineers.
While a book like this is definitely a great help to developers and scientists who want to improve their ability to communicate their ideas, I wonder how many managers of the sort I've described will use it as a tool to devalue the work of professional technical writers.
Just because you can write, it doesn't mean you can write well.
Re:Like a breath of fresh air (Score:1, Insightful)
I've found that it's just a sign of laziness or worse, stupidity. I chat on IRC everyday with people who speak English as a second or third language, and their English is impeccable. We consistently ridicule English speakers who just can't be bothered to spell properly. Those who don't speak English well enough to be understood, get "referred" to other channels where they can chat in their own native language.
The Problem With Technical Writing (Score:2, Insightful)
I wrote many maintenance manuals in the Air Force and my coworkers never had any problems following the procedures in my manuals. The secret to authoring an effective technical manual is not rocket science. Write as you would speak, and have simple 1,2,3, etc steps. The average reader will not have any problem understanding your writing. And yes, I did not run this through a grammar or spelling checker. I write as I speak.
Re:Communication is not bureaucratic fluff (Score:2, Insightful)
Code in comment rule of mine: 1 line of comment per line of code, max.
Other rule of mine: If you can't explain your program to a project manager, he's not going to be able to explain it to other people.
Value added: Ah, if you the coder don't know why you're writing the code, how do you know you're doing it right? The recs? I'm lucky if I have a screenshot with hand-drawn lines.
Re:There's another school of thought (Score:3, Insightful)
I've found, as a programmer, and as a general "techie", my years of experience doing Quality Assurance (QA) has been rather valuable. I've learned from multiple former employers that they'd have increased my salary to match or beat the job I was leaving for if they knew how few programmers with good writing skills existed. I was forced to leave one company because they offered me $48k with sparse benefits to relocate to a place with 2x the living expenses (I was making $30k at the time). I now live in the same place, earn (take-home pay) about the same, and my former manager is kicking herself for letting me go so easily.
Anyone who's in a technical field should seek more opportunities to write. Get involved in open-source; OSS is always in need of people willing to write docs. Get on an IRC channel or mailing list where OSS devs frequent, and you'll have them banging on your e-door if you say you'd like to help write documentation. It's great experience, it's a wonderful thing to put on your résumé, and it helps give the OSS community a better public image.
In any case, there is no reason to perpetuate the stereotypical role of engineers and technical people by ignoring such a crucial area as technical writing.
<dune>Long live the writers!</dune>
why writing *really* is important (Score:1, Insightful)
And it's not just the *form* of the documents. It's the arguments why you're right, they're wrong, and you should get every dime they have. There's more to this than simply describing what you did with the belief that as soon as people see your description, of course they'll come flocking to your way of thinking.
Technical writing is more of a war of ideas than anything else. Not only do you have to show your audience you are correct, but you have to address all the hidden questions that they have to convince them that you are correct. Otherwise, what good has all your work been if you can't get others to believe in it?