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)
Re:Like a breath of fresh air (Score:5, Insightful)
Re:Like a breath of fresh air (Score:2)
Re:Like a breath of fresh air (Score:2)
Re:Like a breath of fresh air (Score:2)
Re:Like a breath of fresh air (Score:2)
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.
"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.
Re:Like a breath of fresh air (Score:3, Informative)
Speaking of typos... (Score:2)
I'm pretty sure the submitter meant "writing skills."
Re:Like a breath of fresh air (Score:2)
Its not necessarily that technical people can't put things into a simple to understand format with pretty color graphs and all the right buzzwords - Its often that they just don't have the time. Thats not to say the proper documentation isn't vital or important, just that some people would rather spend their time actually making something work, and others are more interested in making something understood.
That said, if you have
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:Like a breath of fresh air (Score:2)
If your code is beautiful, but nobody can figure out how to use it (because you haven't documented it well), it's only going to be beautiful to you.
In other words, spending time making something understood is part of making something work. It doesn't work unless people can use it.
Communication is not bureaucratic fluff (Score:3, Insightful)
Re:Communication is not bureaucratic fluff (Score:3, Insightful)
Re:Communication is not bureaucratic fluff (Score:2)
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.
I hate to break it to you... (Score:4, Informative)
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.
Re:Communication is not bureaucratic fluff (Score:2)
Even if I can understand the code, why should I wade through it when I don't have to? I want to understand the broad architecture quickly, then deep dive at a particular area of interest. In this kind of environment, too many comments is just as bad as too few.
The "correct" amou
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.
Re:Reverse engineering code is a waste of time (Score:2)
Re:Reverse engineering code is a waste of time (Score:2)
In a very short time, often simultaneously, I can be writing user-level material for software written in C, Java, Cobol, Fortran, Python, Perl, or whatever the language du jour may be.
"Running the code in my head" is not going to work, unless you expect me to master not only English but every other programming language in use, or that has ever been used.
Re:Reverse engineering code is a waste of time (Score:2)
Re:Reverse engineering code is a waste of time (Score:2)
The "why should I have a spec/comments/whatever mindset is what I was railing against. Nobody should have to reverse-engineer or mentally compile code to figure out what it is supposed to do.
Re:Reverse engineering code is a waste of time (Score:2)
What makes you think that the specs or the human-written, non-machine-tested comments will look ANYTHING like the user interface after 12 rounds of user testing? In my experience, specs and comments are just the starting place- by the time a project is shippable, it bea
Re:Reverse engineering code is a waste of time (Score:2)
The preferred practice is to write a draft "as specified" basing it on the product's use cases and functional specs (WHAT it needs to do, not how it does it). Shortly before alpha release, edit the draft to match the reality, add screen shots, etc. If your final product doesn't function like the original spec quite closely, the planning sta
Re:Reverse engineering code is a waste of time (Score:2)
Exactly right- the planning stage ALWAYS gets short changed it seems- and the final round of user testing shows it with fiddling little GUI changes.
Re:Reverse engineering code is a waste of time (Score:2)
Sure thing. But it tends to be a bit difficult to sort out the big picture from the source code. When presented with 1E6 lines of code you are pretty much lost in the forest. You can't see anything but trees.
Providing an outline or a roadmap makes things so much easier. Don't forget you often have to return to this code 6-12 months down the road and it really is a pain to figure out what you
Re:Reverse engineering code is a waste of time (Score:2)
Re:Communication is not bureaucratic fluff (Score:2)
Re:Communication is not bureaucratic fluff (Score:2)
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:Rule#1: Respect your audience (Score:2)
Some consider their parents to be PHBs.
Can someone please explain.... (Score:3, Funny)
Re:Can someone please explain.... (Score:1, Redundant)
Huh... (Score:4, Insightful)
Write it down and when you are gone we will speak nicely of you.
Re:Huh... (Score:5, Insightful)
Why isn't this book called ... (Score:1, Funny)
Re:Why isn't this book called ... (Score:1)
did anyone else read the intro as:
Read on for the rest of Chapell's review, Bitch.
Meh, easy (Score:1)
It's easier than English 101 or English 102.
Just b/c you get an "A" ... (Score:2, Insightful)
I am
Re:Meh, easy (Score:2)
Since you're being picky, you should know that the use of apostrophes to pluralize letters of the alphabet is widely regarded as good practice. Omitting them allows the inappropriate formation of words like "as" and "is".
Re:Meh, easy (Score:2)
I'm not normally one to speak for others in on-line discussions; I automatically question any statement that begins with "Everybody knows that..." or something similar. However, in this case, I think the claim is justified: every book on good writing style I remember reading is consistent on this point.
The Structure (Score:4, Funny)
You mean, like 99% of every other non-reference book out there?
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
Re:Techinical Writing in Progress (Score:1, Informative)
Re:Techinical Writing in Progress (Score:1)
Am I the only one who thinks professors in a technical field who came straight from academia deserve no respect? Where I am going to school there are several Profs who never worked in industry and they are the worst teachers.
Re:Techinical Writing in Progress (Score:1)
Those who can't, teach.
Nice review (Score:4, Funny)
Of course, maybe that shouldn't be surprising, given the book you just read. Sounds good.
One problem (Score:3, Insightful)
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:One problem (Score:2)
In my experience, everyone who can't write worth a damn thinks they can.
Re:One problem (Score:3, Funny)
Read the Elements of style (Score:4, Informative)
worthless... (Score:1)
I get that feeling everytime I have a meeting with the big cheeses.
Why shooud I take tecnical riting? (Score:5, Funny)
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?
YES! (Score:2)
Boing!!! (Score:1)
A spring vividly and concisely summarizing a technical spec.
The art of technical report writing... (Score:2, Funny)
Ragged-right (Score:2, Informative)
How does this compare to... (Score:1)
Re:How does this compare to... (Score:3, Informative)
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
Re:How does this compare to... (Score:2)
There's another school of thought (Score:2)
If I have to support one more system written by folks like my father, who lived by that creed, the next time you'll see me will be in the evening news.
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
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: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.
Re:Explanation as a Debugging Tool (Score:1)
I think Feynman said something to the effect that if you could not explain a topic to bright freshman in the same field, then you really don't know it that well yourself.
Knowing how to Format a Document is Great... If... (Score:1)
None of that will help my coworkers. They need a reading class, followed by a book on how to construct a sentence.
WTF is the article talking about?? (Score:1)
All your grammar are belong to us (Score:2)
I'm not worried about my job! (Score:4, Funny)
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.
Amen, brother! (Score:2)
Same thing is true of writing. More so. It's amaz
Types of verbs (Score:2, Funny)
I can name lots of types of verbs! English verbs, Spanish verbs, Mexican verbs, Japanese verbs, ...
Re:Types of verbs (Score:2)
Re:Types of verbs (Score:2)
Mexicano: "No me chingues!"
Another good book (Score:2)
1337 Speak (Score:2, Funny)
Re:1337 Speak (Score:2)
I believe a strange language known as "English" is customary in this part of the world. You may find an ancient text known as a "dictionary" to be helpful. (It's like a paper spelling checker.)
Rumour has it that particularly skilled English speakers, sometimes called "five year olds", can even convey meaning clearly and precisely using a strange concept called a "sentence". This obviates the trad
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:What's the Point? (Score:2)
The hardest thing to write is a clear, concise explanation ... I've been a technical writer for 20 years or so and I'm STILL LEARNING. However, the core techniques of writing non-fiction can be taught fairly quickly.
I'm afraid that the book's author may have spent a lot of time on layout, which is probably something better left to a professional.
Re:What's the Point? (Score:2)
The King's Singing Horse (Score:2)
But how much effort might be required to raise the standards of written communication within people whose time might be better spent doing what it is that they do best? My point is that the effort might be too much, and too distracting, and ultimately futile because the tech writer is still going to have to rewrite it all anyway. There's a reason why "division of labour" works so well in a large enterprise.
Are you fa
Re:What's the Point? (Score:2, Informative)
Read Closer (Score:2)
Why don't you point out where I said that? Communication is a two-way process. It requires comprehension as well. I said "past a certain point". Implicit in my argument is that people are able to communicate in such a way as to obtain a passing grade in a college-level language composition class. With that skill, any reasonably able person should be able to learn to communicate effectively the systematics of their
Maybe I'll use this book... (Score:1)
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.
Explanation of *how* things work is crucial. (Score:2)
The industry is in dire need for more people to write for the *need* of other people.
Two current examples.
My company employ one of the big development methods, aging back some 10-15 years. It contains templates for various (document) deliverables the company pitch as an advantage to customers. These documents (ranging from 80-500 depending on the project) are something each project spits out *just because* they have to (lousy project management). The decision o
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 "t
Re:Tech Writing Rant (Score:2)
- I am treated very well.
- The developers are sweethearts and go out of their way to help you out when you don't understand something. They are very cooperative, helpful, and good communicators.
- The developers, though non-native writers of English, write excellent notes and reviews.
Maybe I'm just very lucky, maybe it's a cultural (both country and corporate) thing. We all seem to have
Re:Tech Writing Rant (Score:2)
Aside from getting 5 years of FrameMaker experience, anything else you could recommend?
how to start after doing other things (Score:2)
Once you have something to show a potential employer, start applying for jobs.
Couple of links (Score:2, Informative)
Technical writing tips: http://www.docsymmetry.com/index.html [docsymmetry.com]
Plain English Campaign: http://www.plainenglish.co.uk/index.html [plainenglish.co.uk]
Get it write: http://www.getitwriteonline.com/archive/tips.htm [getitwriteonline.com]
Re:Disagree (Score:2)
Re:Disagree (Score:1)
Re:Disagree with the disagreer! (Score:2)
Does your source code start with a clear software specification document, and are all your mudulkes accurately and completely commented? If not ... what the heck are you coding?
Re:Disagree with the disagreer! (Score:2)
Re:Sweet word "mudulkes"! (Score:2)
Re:My thoughts... (Score:2)
Re: (Score:2)