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.
Techinical Writing in Progress (Score:4, Interesting)
At that point, the student should have gone on a co-op [wikipedia.org], so the student should have some knowledge and insight into having something techinical to write about.
The courses are taught by professors who have experience in the workplace environment (not professors who came straight from academia).
all in all, the setup is wonderful for making a writing class useful and moderately enjoyable.
--mike
Explanation as a Debugging Tool (Score:4, Interesting)
I'm not talking about walkthroughs.
What I mean is, when you are stuck -- when you have been staring at your code for hours, but you just can't see where the problem is -- you go and explain how it works to someone else.
It doesn't even matter if the other person is understanding, because, after just a couple minutes, the explanation usually ends something like this:
"And in this line, we take the value that was stored up h-e-r-e... uh... wait a minute... [inaudible mumbling]... I gotta go, I'll see you later."
Re:Like a breath of fresh air (Score:5, Interesting)
I think the second half of that is more on target than the first. A lot of techies aren't willing to put in the time and effort to present their work well: because it's hard, because they lack confidence in their writing and speaking or just because it's not fun. And then they hide behind the excuse that speaking and writing poorly is a sign of 1337-ness.
The problem is that for a lot of jobs, the maxim the reviewer brushed off is entirely true. If you can't explain what you did, you might as well not have done it.
Re:Explanation as a Debugging Tool (Score:5, Interesting)
In the office in which I work, people often come up and state explicitly that they need to do some confessional debugging, and it almost always works. Sometimes it requires a question or two from the listener, but thats usually the most the confessor needs.
Tech Writing Rant (Score:2, Interesting)
Many developers (not mine of course), especially in poorly managed and I mean both poorly tech and people managed departments treat Documentation as Chore and Necessary Evil, and Quite Honestly treat the Tech Writers like s#@t. The developers don't want to provide guidance, provide content and review docs. The managers are afraid to put thier foot down on thier "talented whiners" so it becomes OK. And then they throw in the Agile Manifesto, to try to justify it.. you know code over documentation... agghhhh it drives me crazy... not the Product Documentation you Moron! In the end it is the product that suffers.
These are the same developers that then turn around and complain about crappy documentation in the tools and platforms they use.
Finally I don't buy that "Engineers are poor writers by design". Step up to the plate Maynard! and learn to read and write!
As others said engineers that learn to write and communicate become much more valuable, and have a greater chance to effect the process. If you don't like what your manager is saying, learn to communicate your ideas effectively. Its up to you to be your own best advocate.
-Steve