Slashdot Mirror
Spring into Technical Writing
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 StructureThe 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.
ConclusionThis 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.
I think a book of this type is desperately needed, and I applaud the author. I for one am so tired of going to meetings where you get the "ass-kisser" type who can talk like a bigshot (yet does NONE of the work) taking all the credit. I work alongside some of the most brilliant engineers who are always overlooked for promotions or new opportunities simply because they aren't good at presenting or adding the burecratic fluff for managers who don't know a damn about what's involved behind the scenes.
"Simplify, simplify, simplify!" Thoreau
This is why we are re-doing the software on all of our servers. We had 2 bozos building servers that were really bad at documentation. Policys scattered everywhere. We are also having to configure all of our switched from scratch, too.
Write it down and when you are gone we will speak nicely of you.
There's a mandatory course at my university in regards to technical writing. All engineers have to take it. It's much better than the standard 'college writing' class (think boring lit times 10). in fact, students can only take this course in their third year or later (NU is a 5 year school).
At that point, the student should have gone on a co-op, 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
When I went to Law School and Business School this book was praised: The Elements of Style by Strunk available here: http://www.bartleby.com/141/
My riting is just grate. I don't need there book to tell me how to rite better.
Now I goota get back to my tecnical documenteation for this project I'm dooing over hear.
BTW, wat excactly does a java inturfaice do again?
While I applaud the author too, everyone needs to recognize that there is no substitute for "caring about the reader," and quite frankly, most technical people don't have the time (or want to expend the time) to learn how to explain themselves to a non-technical audience. More specifically, we don't feel that the audience is worth this expenditure of time.
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
My friends and I have long known the power of explaining your code as a method of debugging.
:-)
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."