Forgot your password?
typodupeerror
Technology Books Media Book Reviews

Spring into Technical Writing 173

Posted by timothy
from the words-on-screen dept.
Simon P. Chappell writes "There is a school of thought that if you cannot explain what you've done, then what you did was worthless. Perhaps that attitude is a little extreme, but in this highly networked world of emails, instant messages, wikis, blogs and webpages, the art of explaining oneself well is important. While there are many books that teach written skills, there have been few ostensibly aimed at technical folks. Enter Spring into Technical Writing for Engineers and Scientists by Barry J. Rosenberg, a technical writer and the author of a number of technical articles and books including the KornShell Programming Tutorial." Read on for the rest of Chappell's review.
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.

This discussion has been archived. No new comments can be posted.

Spring into Technical Writing

Comments Filter:
  • by bigwavejas (678602) * on Thursday July 21, 2005 @04:33PM (#13129468) Journal
    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.
    • by `Sean (15328) <sean@ubuntu.com> on Thursday July 21, 2005 @04:38PM (#13129531) Homepage Journal
      A book on technical writing is all well and good, but quote a few geeks still need assistance grasping basic writing. I still say [slashdot.org] that Elements of Style [amazon.com] should be in everyone's backpack or briefcase.
    • While I think what you say is very true, there is another element to it.

      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
      • by Otter (3800) on Thursday July 21, 2005 @05:10PM (#13129844) Journal
        Its often that they just don't have the time...some people would rather spend their time actually making something work, and others are more interested in making something understood.

        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.

      • 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.

    • by Anonymous Coward
      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.
    • by TimTheFoolMan (656432) on Thursday July 21, 2005 @04:58PM (#13129738) Homepage Journal
      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
  • by Linuxthess (529239) on Thursday July 21, 2005 @04:33PM (#13129475) Journal
    What the hell was he just talking about?
  • Huh... (Score:4, Insightful)

    by Tikicult (901090) on Thursday July 21, 2005 @04:35PM (#13129496)
    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.
  • by Anonymous Coward
    ... Technical Writing Hacks for Engineers and Scientists?
  • I took a Technical Writing course last semester in college. I didn't even buy the book, and I passed with an easy A.

    It's easier than English 101 or English 102.
    • doesn't mean you deserved it. With colleges forcing grad students and junior faculty to meet quotas regarding grades, an "A" is very rarely the result of your hard work in a course like technical writing. In addition, technical writing courses rarely deal with things like specs and design documents in a realistic fashion. The teachers in these kind of courses are meant to analyze very basic elements that revolve around following instructions more than writing a spec that is easy to understand and use.

      I am
  • by intmainvoid (109559) on Thursday July 21, 2005 @04:35PM (#13129505)
    The book is split into four sections, each building upon the output generated in the previous section.

    You mean, like 99% of every other non-reference book out there?

  • by fwice (841569) on Thursday July 21, 2005 @04:36PM (#13129512)
    There's a mandatory course at my university [neu.edu] 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 [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
    • Most universities (of which I am aware) have 2 different mandatory 'English' classes - a technical writing class for engineers, math/physical sciences majors etc., and a general class for non-technical majors. However, from indications I've gotten from friends and colleagues (including an actual technical writer), these classes are woefully inadequate at preparing one for the workplace. This book looks good, and I enjoyed the review.
    • not professors who came straight from academia

      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.

  • Nice review (Score:4, Funny)

    by 14erCleaner (745600) <FourteenerCleaner@yahoo.com> on Thursday July 21, 2005 @04:36PM (#13129513) Homepage Journal
    That was a surprisingly well-written, easy-to-read review.

    Of course, maybe that shouldn't be surprising, given the book you just read. Sounds good.

  • One problem (Score:3, Insightful)

    by Anonymous Crowhead (577505) on Thursday July 21, 2005 @04:38PM (#13129533)
    In my experience, everyone who can't write worth a damn thinks they can.
    • by securitas (411694) on Thursday July 21, 2005 @05:48PM (#13130144) Homepage Journal


      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.
    • In my experience, everyone who can't write worth a damn thinks they can.

      ...and are uniquely qualified to submit stories to, or even become an editor on, Slashdot.

      ;-)

    • Funny. I've noticed that problem also exists in the area of software design.
  • by wsxian (689313) on Thursday July 21, 2005 @04:45PM (#13129600) Homepage Journal
    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/ [bartleby.com]
  • "if you cannot explain what you've done, then what you did was worthless"

    I get that feeling everytime I have a meeting with the big cheeses.
  • by pg110404 (836120) on Thursday July 21, 2005 @04:53PM (#13129685)
    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?
    • YES! People who can't write or speak well also don't have a good understanding of the concepts. It's just the way it is, and the way it has to be.
  • boing boing, boing boing boing boing-boing, boing boing-boing boing. Boing-boing boing boing boing boing boing.

    A spring vividly and concisely summarizing a technical spec.
  • I was going to say something mean about technical report writing, but I can't really describe correctly exactly how I feel about this subject.
  • Ragged-right (Score:2, Informative)

    by tsanth (619234)
    I didn't like the ragged-right text justification
    Actually, ragged-right text justification is often used to allow the eye to follow the text more easily.
    • 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
  • There is a school of thought that if you cannot explain what you've done, then what you did was worthless.
    If it was hard to write, it should be hard to read.
    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.
    • There is a school of thought that if you cannot explain what you've done, then what you did was worthless.

      If it was hard to write, it should be hard to read.

      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

  • by Anonymous Coward on Thursday July 21, 2005 @05:06PM (#13129808)
    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." :-)
    • by Miniluv (165290) on Thursday July 21, 2005 @05:36PM (#13130052) Homepage
      There's even a generally recognized named for this. In The Pragmatic Programmer this is called "Confessional Debugging". You are quite right about both its usefulness, and the standard usage pattern.

      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.

    • The exercise of explaining any topic, not just source code, is a good learning tool as well for that topic. Even if it just a mental exercise where you are explaining something to an imaginary listner and you try to predict what kind of questions might arise.

      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 very important. It's good to know how to use even amounts of white-space, group like items, and differentiate unlike items. If you can do all that, and remember to use sans-serif (no strikes) fonts for headings, and serif (strikes) fonts for body text, then you just might make one sexy looking document.

    None of that will help my coworkers. They need a reading class, followed by a book on how to construct a sentence.
  • I don't fvcking have issues communicating apples banana blue octopus! Different hands ordain opposite monkeys but fantasy microwaves and cell phone puppies. Seriously, fighting and screaming however, beer beer beer. Beer beer beer beer beer. Just remember this, beer.

  • 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.
    I can't decide if that's wrong or not, but it definitely jars.
  • by Tsu Dho Nimh (663417) <abacaxi&hotmail,com> on Thursday July 21, 2005 @05:23PM (#13129925)
    I'm a professional technical writer ... and I'm not going to worry that engineers or programmers will learn how to write so well that I'm redundant.

    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.

    • As an ex-programmer, now technical writer too, I know exactly what you are talking about. Can anyone read a book on programming and become a programmer? Pretty much. How good a programmer will most of those people be? Average, or not very good at all. You have to have a certain mindset, a way of thinking that allows for clean code. If you don't have that, you can learn the language and some algorithms, but your code will never be a joy to work with.

      Same thing is true of writing. More so. It's amaz

  • If you can name more than one type of verb

    I can name lots of types of verbs! English verbs, Spanish verbs, Mexican verbs, Japanese verbs, ...

  • Writing for Computer Science [justinzobel.com] by Justin Zobel [rmit.edu.au] is also a very good book in this area. It focuses on academic writing but has a lot of detail on how to create good figures, graphs, tables and so on.
  • 1337 Speak (Score:2, Funny)

    by BinBoy (164798)
    I'm disappointed with the lack of a 1337 speak chapter. How can I explain myself to my colleagues on IRC?

    • I'm disappointed with the lack of a 1337 speak chapter. How can I explain myself to my colleagues on IRC?

      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)

    by meehawl (73285) <meehawl,spam&gmail,com> on Thursday July 21, 2005 @05:39PM (#13130082) Homepage Journal
    I think it's a bit of a wasted effort for engineers to try to learn to communicate in English past a certain level. A college freshman scientific writing/essay course should be sufficient. Unless, of course, they are career changers and *want* to move into technical documentation. Usually, though, the tendency is to move in the other direction.

    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.
    • " I think it's a bit of a wasted effort for engineers to try to learn to communicate in English past a certain level. "

      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.

    • I worked with many intelligent engineers at one job and by the end of the second month was delivering most of the powerpoint presentations because they had never, in their professional careers (the shortest of which started when I was still watching Transformers) learned how to explain technical concepts to a non-technical audience. We had one brilliant professor whose idea of a demo was to have scrolling output from a unix script running by at the computer's maximum speed -- he assumed that since he could
      • It is not wasted effort to learn to communicate effectively in spoken and written English

        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)

      by writingdoc (901981)
      A class you took as a first-year college student is not going to help you much when you start working and trying to a) learn new technical stuff in a real work environment and b) communicate it to people without your expertise. Sorry, but that's the "great writing inoculation hope." It's been a hope for a long time, and it's never panned out (see David Russell's book Writing in the Academic Disciplines if you'd like a detailed history of just how long people have wished this were true, and just how much it'
      • For me to hear you say that engineers don't need to communicate clearly is, frankly, scary.

        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 in Writ 1E in college. A special writing class desgined for illeterate engineers like me :-)
  • Most technical writers do not write as they speak, and they do not write in simple step 1,2,3 steps.

    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.
  • This seems like an excellent book and subject.
    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)

    by bossvader (560071)
    I am a Development Manager who came up through the ranks and have a wife that is an excellent Tech Writer. Here are a few of our observations...

    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

    • I am a tech writer now; I wasn't one until very recently. Anyway, here's my experience in the company I work for:

      - 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

      • How did you break into the industry? I've been considering it as a (slightly more) offshoring-resistant (not -proof, of course) career with respect to software development. I can kinda write good, as well, and really wouldn't mind a career in documentation.

        Aside from getting 5 years of FrameMaker experience, anything else you could recommend?

        • Very simply - start writing stuff. Documenting Open Source projects is a great way of getting experience and building up a sort of portfolio of proof that you actually can write.

          Once you have something to show a potential employer, start applying for jobs.

  • Couple of links (Score:2, Informative)

    by JerryP (309597)
    If you're interested in the book's subject, you might find the following links usefull:

    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]

God may be subtle, but he isn't plain mean. -- Albert Einstein

Working...