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.
You mean, like 99% of every other non-reference book out there?
Drag n' Drop DVD Recommendations
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
Of course, maybe that shouldn't be surprising, given the book you just read. Sounds good.
Have you read my blog lately?
In my experience, everyone who can't write worth a damn thinks they can.
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/
Communication in language is as technical an achievement as communication in code. It takes a little learning and a lot of practice. It is far from "ass-kissing" or bureaucratic fluff. Almost EVERYONE has problems with the written and spoken word. This is not some downfall of geeks only. And your code is only as good as your communication skills if you are working on a team or anyone other than you will need to read the code. Geeks need to see good communication as a technical challenge, which it is.
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."
A Guide to Writing as an Engineer?
I used this book when I went to college, and found it very useful when writing a variety of papers, from cover letters to resumes to technical reports. It quickly became one of the first books I reached for when writing any technical documents, such as a final report describing an AI program that I wrote in my senior year. I highly recommend it.
I was exposed to this book primarily because I was a CS student at an engineering college, and it often makes me wonder what my CS studies/reports would have turned out without this resource book by my side.
However, if they could just learn to write a decent paragraph or two explaining the way their newest brain-child REALLY works, I'd be a very happy writer.
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.
but if your code work does not either cut expenses or add revenue to your employer/client by at least the cost of your labor, expect to be out of a job soon*. That's all "value added" really means.
Also, comments matter as much if not more than the code. I'm not talking about stupid crap like:
I've seen stuff like that, and it's worthless. But real comments stating what problem you're trying to solve, and how you're solving it. Without that, what's to say the code is right or wrong? It's so easy to duff up a complex condition with misplaced punctuation or an AND in place of an OR. Explaining this condition in the code will help yourself and others understand what you mean when the code isn't quite saying it. Meatspace is still the Real World(tm), no matter how much we might wish it were otherwise.
* - an obvious exception is basic research work where it's pretty hard to quantify the value of what's done. Another exception is stuff one writes for the pure joy of it.