 * |  .NET and human factors by Jeff Atwood | |
August 25, 2006
How to Write Technical Documentation
I was browsing around the CouchDb wiki yesterday when I saw Damien Katz' hilarious description of how technical documentation really gets written. You know, in the real world:
Welcome to the world of technical documentation!
The situation you are in is no different from any other tech writer. The technical writing process:
- Ask engineer how the damn thing works.
- Deafing silence.
- Crickets.
- Tumbleweed.
- Just start writing something. Anything.
- Give this something to the engineer.
- Watch engineer become quite upset at how badly you've missed the point of everything.
- As the engineer berates you, in between insults he will also throw off nuggets of technical information.
- Collect these nuggets, as they are the only reliable technical information you will receive.
- Try like hell to weave together this information into something enlightening and technically accurate.
- Go to step 6.
Ok, you're not the doc writing type. That's okay, neither am I. However, people are already working to make this better, and I will continue to do so.
I think I've been on both ends of this exchange at some point in my career. It's funny because it's true. I'm sure I've read descriptions exactly like this on Mike Pope's blog.
Posted by Jeff Atwood at August 25, 2006 11:59 PM | TrackBack
The good tech writers I knew used an audio recorder for step 8.
Teman on August 27, 2006 03:32 PMAs a tech writer, I find it's a hell of a lot easier to take the program and figure out how it works myself.
Beth on August 27, 2006 05:18 PMHeh, heh. We've been trying out having the developers scrawl some useful but geeky notes on the wiki once they finish on feature. The notes are details of the actual implementation that testers and tech writers might use to help get them started.
Seems to working not too bad so far.
Paul Norrie on August 27, 2006 05:48 PMSad but true. Of course, I would blame the developer since, if they have built something without any use cases, requirements or screen layouts that specify what that something is, then it is highly likely that what they have built won't do any non-technical user any good. Additionally, I'd blame the tech writer since, if the software is nearly complete and they have not raised any red flags about missing use cases or requirements then they have very clearly dropped the ball. And, of course, I blame management who consistently lets this happen over and over and over again.
One day at my last employer, who shall remain nameless - let's just call them the Pit of Hell, I was walking down one of the corridors and encountered one of my peers. I pointed at a nearby cubicle and said "That is what is wrong with this company". My peer stared at me in a very strange way - what could be wrong with a developer and a technical writer sitting in the developer's cube having a work related conversation? I've always thought the battle is lost when a developer and a technical writer are talking; the vast majority of the time, although they seem to be speaking English, in reality they have no common language.
Marketing literature is the same (if not worse). Another time at "The Pit", I read a press release for one of our soon to be released products; we'll call it Pixie Dust for sake of a name. I picked up a printed copy of this press release and walked over to my friend's office; she was the technical lead for Pixie Dust at the time. I asked her if she thought it strange that we had two products called Pixie Dust since this press release very clearly had nothing to do with the product she was building.
Tim Dudra on August 28, 2006 01:32 AMNot sure why one would go to the developer? I prefer to play with the software myself, read/decipher business requirements and specs, and if all else fails, go to the business analyst, product manager, or whoever designed the thing and wrote the requirements/specs.
Lisa on August 28, 2006 11:08 AMLet's just be honest here:
If you could really write, you'd be publishing your novel and polishing your pulitzer.
If you really understood computers/code, you'd be coding your own apps.
Let's just be honest here Armen: Those are two incredibly stupid statements.
Firstly, just as there is a huge difference between writing GUI code and server code and test driver code, there is a huge difference between doing technical writing and fiction writing. I doubt J.R.R. Tolkein could have written good technical documentation and I can't imagine Steve McConnell (of Code Complete fame) pounding out a fantasy thriller.
Secondly, if someone wanted to code their own applications, why would they let something as unimportant as not really understanding computers/code get in their way? It hasn't stopped a significant percentage of software professionals.
With my tongue somewhat in my cheek,
Somewhat sincerely,
Tim
Nice post. Thought provking.
Paul's approach is a good attempt. Seems to be working for him.
Lisa and Beth seem to have a can-do attitude to the situation.
This got a little long as I wrote it, and it's probably a bit off topic, but what the heck...
In a perfect world, specs would be frozen, use cases would be complete, and clients would be realistic in terms of cost and schedule. (Ha! If you live in that world, consider that you have a great job.)
In the real world that most of us inhabit, none of these is the case. Developers who can't, or more accurately, refuse to learn to write and speak coherently are the root of this problem. Let's be honest about the situation -- project managers, business analysts, tech writers, and clients aren't stupid. They just don't understand code, add we, as developers, shouldn't expect them to. It's our responsibility to help them with the technical intricacies that need further explanation.
I hear developers whine all of the time about crappy specs. It's almost as though developers expect a magical, frozen document to be produced that can be used as the basis for code specifications, technical documentation, user guides, marketing materials, etc., etc., etc. If that kind of document could be written, then what's the need for developers, tech writers, marketing, etc., etc., etc.??? The work is already done! It's a team effort, guys. We all need do our part.
If the spec is crap, don't write code against it until you clarify what you should do. ASK A QUESTION OR TWO. Understand what you are doing. If you don't understand the purpose of the feature you are writing, and you can't ask a sensible question, then I wonder what your real value is to your organization.
If all you want to do is code to spec, and you demand a *perfect* spec, and you're not willing to ask questions when what you've been asked to do doesn't make sense to you, then you've turned your job into EXACTLY the kind of menial work that is being outsourced to India in droves. Developers need STEP UP and become more useful and cooperative team members, or suffer the consequences.
And yes, I *am* a developer -- not a suit. I just refuse to put my name on something that I can not defend. If I don't know how (and why) it does what it does, pointing to a crappy spec doesn't help me -- it only hurts my co-workers (those PMs and BAs), who I should be supporting. Why would I want to set up a "me vs. them" situation?
Leave the egos at the door. Work for your team's success, or get the f--- out.
Jeff - but not that Jeff on August 28, 2006 07:23 PMLet's be honest with Armen here:
If you could really write programs that worked properly, you wouldn't need a tech writer to tell your users what you really meant the program to do, and to tell them how to fix up the mess when it doesn't do it.
And if you think you do that already, that's because you can't write or talk to users, which is no great surprise.
Or if you could really code things properly, you could just write a compiler for the requirements specs and go home early the first time it happens. (No second time needed.)
PeterM on August 28, 2006 10:02 PMJeff,
I reckon the error lies right at the beginning, at step #1:
>>Ask engineer how the damn thing works.
Nope. Read through all the literature available: your specs, design docs, the whole thing BEFORE you approach the engineer. Which'll enable you to keep the engineer on guard because of your well-preparedness. I follow this. Works everytime, like a charm.
Tech writers looking for developers/engineers for help are kidding none but themselves, and then they complain "we're not respected."
Sandeep on August 28, 2006 10:31 PMHey Jeff - but not that Jeff! Great response. I agree completely except for one point. You say "I hear developers whine all of the time about crappy specs". Now, I've worked in just about every kind of job you can find in an R&D department so I have been a whiney developer, a sloppy spec writer, a tyrannical project manager, an ivory towered architect and I've dabbled in dreaming the impossible dream (product management) and I'm sure I'm missing some other stuff too. Heck, I'm even one up on Tolkein and McConnell in that I've done some technical writing that was fiction.
That said, when writing specs it was my honest opinion that many of our developers whined about the specs being incomplete if the work being spec'ed sounded boring, would require them to overhaul their existing Objects' d'Art, force them to interact with their peers or bothered them religiously. By whining and demanding "clearer specs" they could delay the odious work and hopefully have it dropped due to deadline pressures. On the other hand, if what was being spec'ed seemed interesting or fun, they were quite content to charge ahead with even the most minimal of specs (especially if the specs were so minimal they could interpret them however they wanted).
Now, before everyone thinks I'm bashing developers - program managers and product managers and QA people were all quick to bash the developers and often wouldn't initiate conversations with them because they would have to step outside their own comfort zone in trying to understand the technicalese. PMs would spec stuff that was very expensive or quite possibly NP-complete and get frustrated when the developers said "it can't be done". Of course, there was always the boy who cried wolf syndrome to be considered since the developers had already cried "it can't be done" three times already.
Peter, you're bang on too.
Tim Dudra on August 28, 2006 10:38 PMSo, is this we get documentation that explains the "WidgetMode" check box as "Enables WidgetMode"? No shit, really?
Doug on August 29, 2006 01:45 PMI'm a technical writer. I think of my work as translating Geek to English. That's the job, guys; you do need to speak enough Geek to merit the "technical" part of the job description.
So while there are plenty of developers who make the tech writer's life a misery, there are also plenty of tech writers who need to work harder at their translation skills. And as several people noted, that means reading - and understanding - all the specs and design documents.
Molly O'Scribe on August 31, 2006 01:03 PMIf I relied on the so-called "specs" from the developers, I _would_ be a successful fiction writer.
Most times when I get tech/func specs from development, they are so full of implementation possibilites (we could do this... or we could do that) and commented questions, that oftimes, the only resemblance the own to the finished product is their name. Sometimes they are just enough to get the thing working and then we can write something worth using.
The times when we have worthless specs and must document from an app are frustrating and typically end with a few lines of fluff because it's impossible to drive the app without knowing how to setup the background data.
Some of my developer's produce decent specs to write from. Our app is extremely complex. There are probably not more than two or three people in the whole company who are proficient enough to demontrate all of its features (and that would take several days to do). These developer's are irreplaceable. Unfortuantely, there aren't many of them.
Trent The Thief on September 1, 2006 04:47 AMTrent: I hope you have a decent editor.
I get really exercised when I find mistakes like these from people who are supposed to be making their living writing in English.
"the only resemblance the own"
they own
"how to setup"
set up
"Some of my developer's produce decent specs to write from."
Some of my developers produce [it would only be developer's produce if we're talking about carrots!] decent specs FROM WHICH TO WRITE.
"Unfortuantely"
Unfortunately [Okay, I'll give you this one; it's just a typo.]
| Content (c) 2006 Jeff Atwood. Logo image used with permission of the author. (c) 1993 Steven C. McConnell. All Rights Reserved. |
