Beta
×

Welcome to the Slashdot Beta site -- learn more here. Use the link in the footer or click here to return to the Classic version of Slashdot.

Thank you!

Before you choose to head back to the Classic look of the site, we'd appreciate it if you share your thoughts on the Beta; your feedback is what drives our ongoing development.

Beta is different and we value you taking the time to try it out. Please take a look at the changes we've made in Beta and  learn more about it. Thanks for reading, and for making the site better!

Spring into Technical Writing

timothy posted more than 9 years ago | from the words-on-screen dept.

Technology 173

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.

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.

Sorry! There are no comments related to the filter you selected.

Like a breath of fresh air (5, Insightful)

bigwavejas (678602) | more than 9 years ago | (#13129468)

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.

Re:Like a breath of fresh air (4, Insightful)

`Sean (15328) | more than 9 years ago | (#13129531)

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.

Re:Like a breath of fresh air (1)

`Sean (15328) | more than 9 years ago | (#13129552)

Wow. I suck. I figured I'd smack myself down for the typo before someone else does. :)

Re:Like a breath of fresh air (1)

WindBourne (631190) | more than 9 years ago | (#13129889)

And yet, you did not point it out. Would like to quite it? :)

Re:Like a breath of fresh air (1)

Molochi (555357) | more than 9 years ago | (#13130651)

"Would like to quite it?" Beg your pardon?

Re:Like a breath of fresh air (0)

Anonymous Coward | more than 9 years ago | (#13130689)

./ers jump on your ass like a bloodhound on bacon for getting high-and-mighty on writing and therein misspelling a word, on the basis that (in my case) holding an English degree means you have 100% typing accuracy, have memorized a grammar book, and won the National Spelling B Championships when you were 12.

Of course, the reason this is too much to expect is because English majors are inherently feeble and effeminate. I've never met a Bachelor of Computer Science who wrote buggy code on the first try.

Re:Like a breath of fresh air (2, Insightful)

promantek (866291) | more than 9 years ago | (#13129962)

I agree. Elements of Style is a great book.

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" (2, Insightful)

holden caufield (111364) | more than 9 years ago | (#13130081)

Here is another vote for "On Writing Well" to bookend your copy of Strunk & White.

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 (2, Informative)

cratermoon (765155) | more than 9 years ago | (#13130596)

My recommendation: Style: Toward Clarity and Grace [amazon.com] , by Joseph M. Williams. The main lesson of his book is how to drag your writing out of the context of expert knowledge and assumptions in your head and into a form that communicates what you really meant to people who can't get inside your head.

Speaking of typos... (1)

GPS Pilot (3683) | more than 9 years ago | (#13130198)

While there are many books that teach written skills...

I'm pretty sure the submitter meant "writing skills."

Spring Into Patriotism: ( +1, Patriotic ) (-1, Offtopic)

Anonymous Coward | more than 9 years ago | (#13129544)


and impeach the biggest white collar criminals in the world [whitehouse.org] .

Thanks and have a Rove_Cheney_Bush_Rumsfeld-free day,
Kilgore Trout, CEO

Re:Like a breath of fresh air (1)

ShaniaTwain (197446) | more than 9 years ago | (#13129568)

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 the skills to do both you will suceed at pretty much whatever you try.

Re:Like a breath of fresh air (4, Interesting)

Otter (3800) | more than 9 years ago | (#13129844)

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.

Re:Like a breath of fresh air (1, Insightful)

Anonymous Coward | more than 9 years ago | (#13130162)

the excuse that speaking and writing poorly is a sign of 1337-ness.

I've found that it's just a sign of laziness or worse, stupidity. I chat on IRC everyday with people who speak English as a second or third language, and their English is impeccable. We consistently ridicule English speakers who just can't be bothered to spell properly. Those who don't speak English well enough to be understood, get "referred" to other channels where they can chat in their own native language.

Communication is not bureaucratic fluff (3, Insightful)

Anonymous Coward | more than 9 years ago | (#13129614)

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.

Re:Communication is not bureaucratic fluff (-1, Flamebait)

Marxist Hacker 42 (638312) | more than 9 years ago | (#13129643)

Anybody working on a team ought to be able to read code and understand the internals of the machine. If they can't- they're working in the wrong industry.

Re:Communication is not bureaucratic fluff (0)

Anonymous Coward | more than 9 years ago | (#13129821)

So does this means you learn a new language by reading the code of the compiler ?

Re:Communication is not bureaucratic fluff (3, Insightful)

chris_mahan (256577) | more than 9 years ago | (#13129874)

if you program in python, say, and you understand the python interpreter, but can't speak in a meeting about what value added your program provides, you're still in the wrong industry.

Re:Communication is not bureaucratic fluff (1)

Marxist Hacker 42 (638312) | more than 9 years ago | (#13130182)

Value added is for project managers, not coders. If you aspire to be a project manager fine- but don't make me read through 200 lines of comments for every 150 lines of code. Only the code matters- the rest is just meatspace.

Re:Communication is not bureaucratic fluff (2, Insightful)

chris_mahan (256577) | more than 9 years ago | (#13130430)

I'm a programmer for a fortune 500. You have to explain the code to the project managers.

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.

Reverse engineering code is a waste of time (2, Insightful)

Tsu Dho Nimh (663417) | more than 9 years ago | (#13130000)

"Anybody working on a team ought to be able to read code and understand the internals of the machine. If they can't- they're working in the wrong industry."

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 (1)

Marxist Hacker 42 (638312) | more than 9 years ago | (#13130204)

Who said anything about reverse engineering? Just run the code in your head. It's no harder than understanding comments in English, it's just another language. A simpler one at that, for most computer langages (a notable exception is SQL with it's recursive layers of interpretation, but even that is fairly readable once you get used to it).

Re:Reverse engineering code is a waste of time (1)

Tsu Dho Nimh (663417) | more than 9 years ago | (#13130685)

"Just run the code in your head"

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 (1)

johnjaydk (584895) | more than 9 years ago | (#13130711)

Just run the code in your head. It's no harder than understanding comments in English, it's just another language.

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 were thinking at that time.

Write clear, transparent code by any means and I'll be eternal gratefull but if You don't provide some clues to how You structured the whole mess then You better check for semtex underneth Your car before You start it. This tends to get hard on Your knees after a while...

And remember most of the time the pure sod who wrote the code 6-12 months ago is the one assigned to updating it (You touch'd it last, pal) and short term memory don't last that long...

Been there, done that and have the scars to prove it.

Re:Communication is not bureaucratic fluff (1)

jscotta44 (881299) | more than 9 years ago | (#13130240)

Let us see how reverse arrogance works. Hmmmmm...

Anybody working an a team of humans ought to be able to explain what they are doing. If they can't, they are working with the wrong species.

Yep. That sounds just as stupid as what you wrote. Everyone has skills. Some people have stronger skill than other people. Do you have any idea how many good ideas have died because the "engineer" (term used loosely to cover a wide variety of people who create great stuff) was not able to persuade other people of the worth of the idea/product/service/etc.? Much. Do you know how much mediocre stuff gets into the world because the people in charge of it know how to persuade others to use/buy it? How about I just put Microsoft on the table as Exhibit 1.

Re:Communication is not bureaucratic fluff (1)

Marxist Hacker 42 (638312) | more than 9 years ago | (#13130541)

And as long as we continue to coddle such people, they will continue to outbreed us. If intelligence is going to count for anything at all in the war that is survival of the fittest, then the stupid need to not be allowed to survive.

Rule#1: Respect your audience (4, Insightful)

TimTheFoolMan (656432) | more than 9 years ago | (#13129738)

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

Re:Rule#1: Respect your audience (1)

James_Aguilar (890772) | more than 9 years ago | (#13130583)

In my book, the real problem is that most technical people are incapable even of writing to a technical audience. That, my friends, is what is embarrassing about the current state of affairs.

Re:Like a breath of fresh air (0)

Anonymous Coward | more than 9 years ago | (#13130014)

Good writing of any kind cannot contain "bureaucratic fluff" -- or fluff of any kind. Neither PHBs nor engineers need or want it, and any good book on writing will say this.

In addition to the excellent Strunk & White, I recommend, "On Writing Well", by Zinser.

Can someone please explain.... (2, Funny)

Linuxthess (529239) | more than 9 years ago | (#13129475)

What the hell was he just talking about?

Re:Can someone please explain.... (0, Redundant)

2nd Post! (213333) | more than 9 years ago | (#13129709)

Read the book, and you'll find out!

Huh... (4, Insightful)

Tikicult (901090) | more than 9 years ago | (#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.

Re:Huh... (0)

Anonymous Coward | more than 9 years ago | (#13129514)

Real programmers don't document. It was hard to write, it should be hard to read.

Re:Huh... (5, Insightful)

Marxist Hacker 42 (638312) | more than 9 years ago | (#13129608)

Given today's problems with employer-employee loyalty- I'd rather you keep me around to begin with than to speak well of me when I'm gone.

Why isn't this book called ... (1, Funny)

Anonymous Coward | more than 9 years ago | (#13129500)

... Technical Writing Hacks for Engineers and Scientists?

Re:Why isn't this book called ... (1)

hobbesx (259250) | more than 9 years ago | (#13129906)

Speaking of which,
did anyone else read the intro as:


Read on for the rest of Chapell's review, Bitch.

Meh, easy (1)

CypherXero (798440) | more than 9 years ago | (#13129501)

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.

Just b/c you get an "A" ... (2, Insightful)

ionrock (516345) | more than 9 years ago | (#13129697)

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 not saying you did not deserve your grade, but I am saying that good technical writing in context is not easy.

Re:Meh, easy (1)

darklordyoda (899383) | more than 9 years ago | (#13130156)

You were just lucky.
At Berkeley, with its oh so pleasant grade deflation, Technical Communication for Engineers is a long, involved class that very rarely gives out A's.

Just as unpleasant, though, I'm sure.

The Structure (3, Funny)

intmainvoid (109559) | more than 9 years ago | (#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?

Techinical Writing in Progress (4, Interesting)

fwice (841569) | more than 9 years ago | (#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

Re:Techinical Writing in Progress (2, Informative)

dagny_dev_ (771050) | more than 9 years ago | (#13129548)

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.

Re:Techinical Writing in Progress (1)

Chosen Reject (842143) | more than 9 years ago | (#13129556)

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.

Re:Techinical Writing in Progress (1)

GeneralHorel (851957) | more than 9 years ago | (#13129693)

Those who can make it in the Tech world do
Those who can't, teach.

Re:Techinical Writing in Progress (0)

Anonymous Coward | more than 9 years ago | (#13130336)

And the worst comp sci teacher I've ever had was a guy from Intel who was teaching a university course. What's your point?

Teaching is a skill, and not necessarily one you become expert at in industry.

Re:Techinical Writing in Progress (0)

Anonymous Coward | more than 9 years ago | (#13130166)

Shameless plug for my employer and website:

http://www.uwtc.washington.edu/ [washington.edu]

Certificate classes seem to be all the rage now. "A writing department in the College of Engineering? GASP! Are engineers... ALLOWED to write?"

"Techinical?" (1, Funny)

Anonymous Coward | more than 9 years ago | (#13130270)

It looks like there's at least one word the class didn't help you with :)

Nice review (3, Funny)

14erCleaner (745600) | more than 9 years ago | (#13129513)

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 (3, Insightful)

Anonymous Crowhead (577505) | more than 9 years ago | (#13129533)

In my experience, everyone who can't write worth a damn thinks they can.

Re:One problem / Technical writing (3, Insightful)

securitas (411694) | more than 9 years ago | (#13130144)



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.

Read the Elements of style (4, Informative)

wsxian (689313) | more than 9 years ago | (#13129600)

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]

Re:Read the Elements of style (0)

Anonymous Coward | more than 9 years ago | (#13129696)

nice link... i would just like to chime in that i also have heard nothing but good things for the book.. but as you can tell by my ending sentences in ... that i have a ways to go....

worthless... (1)

odyrithm (461343) | more than 9 years ago | (#13129624)

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

Why shooud I take tecnical riting? (4, Funny)

pg110404 (836120) | more than 9 years ago | (#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?

Re:Why shooud I take tecnical riting? (0)

Anonymous Coward | more than 9 years ago | (#13130294)

You forgot the infamous misuse of the homonyms "to", "too" and "two".

e.g. Some guy took to exams two early in the morning, but forgot too write his name on them.

When I see the word "too" used where "to" should have been, my internal-rage-o-meter spikes madly.

Boing!!! (0)

Timesprout (579035) | more than 9 years ago | (#13129710)

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.

The art of technical report writing... (2, Funny)

VectorSC (721025) | more than 9 years ago | (#13129720)

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.

Re:The art of technical report writing... (1)

VectorSC (721025) | more than 9 years ago | (#13130570)

Thanks. Don't forget to tip your waitress.

8===D ~~~ penis! (-1, Troll)

Anonymous Coward | more than 9 years ago | (#13129727)

FIRST POST

Ragged-right (2, Informative)

tsanth (619234) | more than 9 years ago | (#13129733)

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.

Re:Ragged-right (0)

Anonymous Coward | more than 9 years ago | (#13130003)

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


The ragged-right justification made it easy to follow the review. Especially the bit about not liking the ragged-right justification.

Writing Sklls (0)

Anonymous Coward | more than 9 years ago | (#13129735)

Never buy a book from an author teaching written skills. The author clearly needs to work on his writing skills.

-A12

How does this compare to... (1)

dutchd00d (823703) | more than 9 years ago | (#13129748)

Re:How does this compare to... (3, Informative)

wuie (884711) | more than 9 years ago | (#13129911)

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.

Re:How does this compare to... (1)

El Pollo Loco (562236) | more than 9 years ago | (#13130532)

Holy Shit, other people from Colorado School of Mines!

There's another school of thought (1)

I8TheWorm (645702) | more than 9 years ago | (#13129755)

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.

The Tipping Point (0)

Anonymous Coward | more than 9 years ago | (#13129773)

"There is a school of thought that if you cannot explain what you've done, then what you did was worthless. "

Blink: The power of thinking without thinking by Malcolm Gladwell would disagree with you.

My thoughts... (0)

Anonymous Coward | more than 9 years ago | (#13129796)

There's a mandatory course at my high school [stlawrence.edu] in regards to technical writing. We all have to take it.It's much easier than the standard 'high school writing' class (think about literature, with the stupid old teacher, times 10). in fact, students can only take this course in their junior year or later, even through it so damn easy.

By this point, we've learned how to do stuff, and should have knowledge of writing.

The courses are taught by profs who have little experience in the workplace, after all they've been teaching forever. They come straight from college or something.

All in all, the courses are better than taking the standard literature (much easier!) but I'd rather stay home sick any day.

--tom

Disagree (0, Troll)

coflow (519578) | more than 9 years ago | (#13129805)

if you cannot explain what you've done, then what you did was worthless

If you can't understand what I've done by my source code, then you're worthless.

Re:Disagree (1)

jimicus (737525) | more than 9 years ago | (#13129890)

That's very nice for you. And when your source code is just part of a multi-million line project, and I want to use your software rather than develop it further, what then?

Re:Disagree (1)

coflow (519578) | more than 9 years ago | (#13129943)

I'm sorry, I forgot to include the marks for those of you in the UK. ;-)

Re:Disagree (0, Redundant)

coflow (519578) | more than 9 years ago | (#13129970)

Crap, that's what preview is for...... I meant:

I'm sorry, I forgot to include the <sarcasm> tags for those of you in the UK. ;-)

Re:Disagree (0)

Anonymous Coward | more than 9 years ago | (#13130538)

Then: you complain to the Mozilla Foundation

Re:Disagree with the disagreer! (1)

Tsu Dho Nimh (663417) | more than 9 years ago | (#13130049)

If you can't understand what I've done by my source code, then you're worthless.

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! (1)

coflow (519578) | more than 9 years ago | (#13130192)

I thought it would be apparent and maybe painfully obvious from the context that I wasn't serious. It's not like normal every day users ever get to see source code, and they're ostensibly the ones who need documentation.

Re:Disagree with the disagreer! (1)

Tsu Dho Nimh (663417) | more than 9 years ago | (#13130642)

We were discussing the need for technical writing skills on the part of programmers and engineers ... and unfortunately, the "read my code" attitude is alive and well in the OSS community.

Re:Disagree (1)

JerryBruckheimer (896257) | more than 9 years ago | (#13130306)

Though you admit to being sarcastic in follow-up posts, there is a grain of truth to this when it comes to programmers (not for end users, as you note). Some programmers only use code comments when they're doing something unusual, which is not necessarily a bad practice. If your objects and methods are named well, the reader should be able to figure out the code without comments like this:
//reset home object and increment it by one
home.reset();
home.add(1);

Re:Disagree (0)

Anonymous Coward | more than 9 years ago | (#13130422)

Re:Disagree (Score:1)
by JerryBruckheimer (896257) [slashdot.org] on Thursday July 21, @04:11PM (#13130306 [slashdot.org] )

Oh my god I fucking hate you.

Explanation as a Debugging Tool (4, Interesting)

Anonymous Coward | more than 9 years ago | (#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." :-)

Re:Explanation as a Debugging Tool (4, Interesting)

Miniluv (165290) | more than 9 years ago | (#13130052)

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.

Re:Explanation as a Debugging Tool (1)

MontyApollo (849862) | more than 9 years ago | (#13130069)

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.

Re:Explanation as a Debugging Tool (0)

Anonymous Coward | more than 9 years ago | (#13130629)

This is my philosophy of commenting code. Write the comments as though you were trying to teach somebody else how it all goes together, and not only will this reveal problems in the design, before you actually write the code, but it will also stop one from writing quick hacks that are either difficult or embarrasing to justify in the comments that explain them.

Knowing how to Format a Document is Great... If... (1)

mikes.song (830361) | more than 9 years ago | (#13129832)

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.

WTF is the article talking about?? (0)

brxndxn (461473) | more than 9 years ago | (#13129877)

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.

All your grammar are belong to us (1)

rumblin'rabbit (711865) | more than 9 years ago | (#13129908)

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.

Re:All your grammar are belong to us (1)

hawkeye_82 (845771) | more than 9 years ago | (#13129978)

I think its supposed to be

If you can name more than one type of verb, then you may well be better off sticking with your copy of The Elements of Style.

I'm not worried about my job! (3, Funny)

Tsu Dho Nimh (663417) | more than 9 years ago | (#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.

Amen, brother! (1)

FunWithHeadlines (644929) | more than 9 years ago | (#13130533)

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 amazing how often companies think anyone can write. Why, it's only the language you speak so how hard could it be? Why I could whip out a manual in no time...if I could just get past this project...and then I need to clean my desk...ah, lunch time calls...etc. The manual never gets done. Or if it does get started, they quickly learn how intimidating a blank screen is when you are the one expected to come up with the next sentence.

Don't get me started on what managers write. Their emails are astounding. Astoundingly bad. But that's not atypical in the least. Most people know how to communicate, but not in writing. So enter the technical writer who can do all of the writing that needs to get done, on time, to spec, with good quality. As you said, I'm not in the least worried that some programmer is going to take my job. I can't even get them to write an email telling me what they want me to write. They are so afraid of writing, they would rather tell me on the phone what they want and let me take the notes!

Types of verbs (2, Funny)

Alphabet Pal (895900) | more than 9 years ago | (#13129953)

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

Re:Types of verbs (1)

TERdON (862570) | more than 9 years ago | (#13130180)

Y exactamente cuál es la diferencia entre verbos españoles y verbos mexicanos???

Re:Types of verbs (1)

Alphabet Pal (895900) | more than 9 years ago | (#13130196)

Los mexicanos dicen los verbos mexicanos, y los espanoles dicen los verbos espanoles.

Another good book (1)

VeryProfessional (805174) | more than 9 years ago | (#13129994)

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 (2, Funny)

BinBoy (164798) | more than 9 years ago | (#13130062)

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

What's the Point? (2, Insightful)

meehawl (73285) | more than 9 years ago | (#13130082)

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.

Maybe I'll use this book... (1)

Ecko7889 (882690) | more than 9 years ago | (#13130093)

Maybe I'll use this book in Writ 1E in college. A special writing class desgined for illeterate engineers like me :-)

The Problem With Technical Writing (2, Insightful)

TheBillGates (266114) | more than 9 years ago | (#13130285)

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. I write as I speak.

Explanation of *how* things work is crucial. (1)

chris_7d0h (216090) | more than 9 years ago | (#13130666)

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 of what document deliverables to produce is made something like 1-2 years ahead, which in reality means only 5-10% of them would be useful at the date of shipping.
Instead of having all these tens of thousands of useless crap pages being manufactured, junk which no-one will ever read, it would be much more appropriate if the right people could write about the right thing in a way suitable for the intended audience. Unfortunately this would mean a break from the *method* at various point which seems unlikely at present given the particular company culture. In short, Agility needs to enter the "document manufacturing" cycles as well.

The second example has to do with with doers vs. explainers (is that a word?).
I've run some projects in which we had some brilliant designers and coders, creating the most flexible and elegant designs and implementation. Unfortunately these people either didn't document them or documented them poorly. On each account I took the decision to simply yank the undocumented or poorly documented "elegant" stuff out of the system replacing it with something which average developers were able to explain and understand. The decision might have resulted in worse design, but who really knows. A customer who is going to maintain a solution deserves to be able to understand the architecture and design without having to hire A-grade coders and getting them to document the stuff (fat chance of getting A-grade coders who also document except for "Gamma or Beck"!).
This culture of *just read the code* isn't flying today and brilliant people who can't express themselves are finding themselves having a harder time getting new project contracts.

Tech Writing Rant (2, Interesting)

bossvader (560071) | more than 9 years ago | (#13130713)

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 "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

Load More Comments
Slashdot Login

Need an Account?

Forgot your password?