Fog Creek Software
Discussion Board




Technical Writing

I am a software engineer that would like to improve my technical writing ability. English is not my first language
Is there any resources or links to websites that might help me improve my writing.

Technical Writer wannabe
Monday, June 24, 2002

If you are willing to pay for the training, I've found the "InfoMapping" methods to be very helpful at improving my technical writing abilities.  Here's a link:

http://www.infomap.com

Dougie Fresh
Monday, June 24, 2002

http://freelancewrite.about.com/cs/technicalwriting/

Tony E
Tuesday, June 25, 2002

Going from SW Engineer to Tech Writer is like going from doctor to nurse.

Cheese Optional
Tuesday, June 25, 2002

>Going from SW Engineer to Tech Writer is like going from doctor to nurse.

oh, come on Cheesie, he did not say he wanted to become a technical writer as only and fulltime profession, he just said he wanted to improve his technical writing abilities

Do you have a feeling of getting your hands dirty or something when you actually sit down and write a few lines of documentation from time to time? Now that I think of it, that could be the reason why some of my colleagues are so reluctant to comment their code... :-)

Technical writing skills are neccessary to write good code documentation, good specifications and good design documents, so it is something that every SW engineer can profit from (and his colleagues and other people who have to live with his code even more).

Techie wannabe, I would assume that you can improve your technical writing skills by reading a lot, that is the cheapest, easiest and most entertaining way I can think of. And you will learn some other things on the way as well, depending on what you choose as your reading matter.

Have fun,

Jutta Jordans
Tuesday, June 25, 2002

quote:
"Going from SW Engineer to Tech Writer is like going from doctor to nurse"

Totally disagree. This attitude might be one of the
reasons why there is so much incomplete and
poorly written software documentation, and why
there are so few voluntary documentation writers in
the Open Source community.
Writing abilities are always useful, even if you don't
do it as your full time job.

Christian Knapmeyer
Tuesday, June 25, 2002

For me, writing the documentation is very helpful in thinking about the problem and in better understanding my solution.  If I can't describe it clearly in English, I'm probably not describing it very clearly in code, either.  It's also a great way to develop an understanding of someone else's work.

Dougie Fresh
Tuesday, June 25, 2002

quote:
"Going from SW Engineer to Tech Writer is like going from doctor to nurse"

I'll be sure to pass on this opinion to Brian Kernighan and Dennis Ritchie (my personal gods).

Technical writing is not a poor man's relative to doing technical stuff.  It takes experience and skill to successfully convey the feel and detail of technical process in a non-technical, engaging and informative way.

Technical writing for a non-technical audience should be a requirement for anybody that wishes to be a technical anything as a trade or profession.  That isn't just programmers, or IT  but medicine, architecture, whatever the discipline is.  Because at some point you're going to have to explain and justify what you do to people that aren't technical or in your direct field. 

If you're Einstein its pointless knowing relativity unless you can explain it to someone else, and preferably to the guy who runs the tram you sit on every day contemplating the tram coming in the other direction.

Simon Lucy
Tuesday, June 25, 2002

I do not agree that technical people should be able to very eloquently explain everything to the layman. It's hard enough finding people who are good at the technical stuff, let alone finding the white elephant that on top of technical wizardry is also an ace documentalist or educator. Many other professions accept the concept of a specialist mediator or translator.

Just me (Sir to you)
Tuesday, June 25, 2002

"There are other books that I reread that are relevant in computing. Books on how to write, write English in my particular case, like ``The Elements of Style'' by Strunk and White. I go back and I reread that every few years as well, because I think the ability to communicate is probably just as important for most people as the ability to sit down and write code. The ability to convey what it is that you're doing is very important. "

- Brian Kernighan

Tease the Cheese
Tuesday, June 25, 2002

IMO, one of the best books ever written (and IMNSHO, better than "Elements of Style") is "On writing well" by William Zinnser. I recommend it highly. All my journalist friends have been impressed by it, and all lawyers should definitely read it. ;)

If you're interested, it's at: http://tinyurl.com/h7d

MadMan
Tuesday, June 25, 2002

While I admit that only hiring coders with technical writing ability would restrict your choice, I believe that for any coder, improving their technical writing skills
will improve their productivity. After all,
a design spec needs to be readable or its no use. And the skills are not substantially different writing for other programmers compared with non-programmers.

David Clayworth
Tuesday, June 25, 2002

" ... the skills are not substantially different writing for other programmers compared with non-programmers. "

I tend to disagree. In daily life I am witness to countless discussions between techies. Often these people come from very different areas and or not familiar with the specifics of the other persons project. Yet still, they share a common language, call it a shared world ontology, and they seem to be able to express problems and solutions to each other perfectly adequate. When I see these same people trying to explain something to a non-tech, only one in ten seems remotely capable of communicating more or less effectively. This to me indicates there must be a significant difference.

Now, should we fire the other nine?

Just me (Sir to you)
Tuesday, June 25, 2002

Firing is probably a good solution.

If the techies cannot communicate to the non-techies, then how can the techies understand the requirements / objectives from the non-techies?

Joe AA.
Tuesday, June 25, 2002

Joe A.A. said -

"Firing is probably a good solution.

If the techies cannot communicate to the non-techies, then how can the techies understand the requirements / objectives from the non-techies?"


Programming is *all* communication.

You have to communicate with customers to learn requirements. You have to communicate with your coworkers to coordinate efforts. You have to communicate (via code) with the machine. You have to communicate to the end users via documentation, and any programmers who may take over your software with comments and related documentation. Not to mention that at some point, unless you were born with the knowledge of how to use C++ and Emacs (or whatever tools you use), you had to learn how to use them from someone else's documentation.

Too many programmers have the idea that they don't need to document in any manner beyond their immediate needs. In my experience, much of it stems from arrogance based on one of two misconceptions:

1. The idea that their code is such a paragon of clarity and ease of use that no documentation is required, and/or

2. The idea that they're smarter than others, and it's up to these others to put out the effort of understanding in order to be worthy of using or modifying the software.

I'd agree that firing is quite possibly the best thing to do with programmers who can't or won't produce usable documentation (from the employer's point of view, anyway). I just feel that the programmers in question aren't likely to draw the appropriate lesson from the situation.

Rather than "Documentation is important, and I'd better learn to do it well," I suspect a too-large percentage would think, "That was a lame place to work, and they didn't appreciate me properly!"

Steve Wheeler
Tuesday, June 25, 2002

Joe A.A. == Bella

Anyone else see it?

Anonymous Coward
Tuesday, June 25, 2002

The only reason I want to improve my technical writing is to be able to pusblish papers. I wrote many papers but never published any and I want to change that.

Technical Writer wannabe
Tuesday, June 25, 2002

TechWriter Wannabe: If you do write papers in even a vaguely readable way, your readers will love you for it. Far too many academic papers attempt to demonstrate the writer's brilliance with impenetrable prose.

Both Strunk and White and Zinsser are good for learning how to write well and clearly. However, each publication has its own style. Many academic pubs require that papers be written in the passive voice and suchlike. This is very different from the advice given in the books mentioned above.

A good plan is to read the publication you wish to be published in. Try to write your paper like the best, most readable one in that publication and you'll be on your way.

The only way to learn to write well is to keep doing it. There is a limit to how much your writing will improve if you only read about writing.

"If you can't explain something simply, you don't understand it well enough." Albert Einstein

Sans Fromage
Tuesday, June 25, 2002

I found this helpful, written by a native German speaker:  http://www.icsharpcode.net/TechNotes/TechnicalWriting20020325.pdf

I also like "BUGS in Writing: A Guide to Debugging Your Prose (2nd Edition)" by lyn dupre
http://www.amazon.com/exec/obidos/ASIN/020137921X/qid=1025078684/sr=1-1/ref=sr_1_1/104-2155076-5046367

HansGUlrich

Hans-Georg Ulrich
Wednesday, June 26, 2002

"I found this helpful, written by a native German speaker: http://www.icsharpcode.net/TechNotes/TechnicalWriting20020325.pdf"
that is a p*ss-take, right? i mean "may be understood as easily as possibly" in a document on writing good documents?

pfft
Wednesday, June 26, 2002

Working part time as a teacher, I have found that learning to explain things to newbies really improved my own understanding. ASP (for example) went from being something I "knew" to a second nature, really fast.

Eric Debois
Wednesday, June 26, 2002

If I have two uber-techies that can communicate well to non-techies, why can't they act as the front-end to my other 8 techies that lack the skill but have many other useful skills.
If we interact with "users" or "customers", we do not set up a meeting with the full development team. If we write the user manual, we do not give each developer a chapter to write.
Sure, having a full team of super all-rounders that are top of the range in every imaginable discipline might be utopia, but:

- Where do I find these people in the first place?
- Would hiring a full team of them be cost-effective?

Would it harm a tech to learn better "non-tech" communication skills? No one said or implied this. I am personally convinced it would probably have a positive effect on many of their other skills as well. However, the lack of this skill does not automatically disqualify them from being a valuable contribution to a development team.

Just me (Sir to you)
Wednesday, June 26, 2002

I think the ability to convey technical information to a non-technical audience should be part of a rounded individual.

I wouldn't fire someone because they couldn't communicate with non-technical people, but I would if they couldn't communicate with me.

But if they did find it difficult to communicate what they were doing to different audiences then I would encourage them and give them the opportunity to gain those skills, that ability.

And no, I'm not talking about wrenching someone deep in some debug session and having them explain the handling of widgets across application boundaries to the CEO.

Wrench me from some deep contemplation and I'm likely to be as non-verbal as anyone else.

Simon Lucy
Wednesday, June 26, 2002

You might ask why would a techie be unable to communicate with a non-techie.

The largest "barrier" I have seen is not a lousy grasp of the language, but the insistance of the techie to expect the non-techie to "communicate" in his/her terms - in other words... tell me how to code, do my job for me. 

In this instance, it is a techie performance issue that needs to be treated as such.  Using an interpreter to help a low experience techie may be appropriate, but if the techie is high experience, it would be unacceptable and assigning an interpreter is just a coverup of the problem.

Joe AA.
Wednesday, June 26, 2002

I think the techie/non-techie communication issue comes down to developing/having the ability to accurately describe a thing in several different ways.  I first realized the importance of this when my grandfather went deaf(ish).  You couldn't just repeat the same thing louder and expect him to understand.  You had to keep trying different words until you hit on one that he could comprehend.  "I went to the movies... to see a film... caught a picture..."  "Oh.  A movie."

I think the same thing happens with techies.  Some people only develop their thinking to the technical level.  So when they explain something, all they can do is repeat their own thought processes.  Others can abstract things a bit more, using different frameworks until they find one that their audience can grasp.  But I wouldn't neccessarily demand that skill of everyone on a team. 

Contrary Mary
Wednesday, June 26, 2002

I have known at least a few talented developers who were not able to communicate with a nontechnical audience. It really seems like baking this a main cause of firing someone for this is a case of cutting off the nose to spite the face.

If you want to fire someone for this in the US, make sure that "explaining things clearly in nontechnical language to nondevelopers" is listed as a primary responsibility in the job description and the developer's signature is on that requirement. I know that if I was fired for such cause I'd have the companies ass on a shishkebob by the end of the week.

Not A Lawyer
Wednesday, June 26, 2002

The dude should have stuck to German.

http://www.icsharpcode.net/TechNotes/TechnicalWriting20020325.pdf

A.
Monday, July 01, 2002

*  Recent Topics

*  Fog Creek Home