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:
The good tech writers I knew used an audio recorder for step 8.
As a tech writer, I find it’s a hell of a lot easier to take the program and figure out how it works myself.
Heh, 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.
Sad 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.
I like the tumbleweed part…
xD
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.
Let’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.)
Jeff,
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.”
Hey 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 RD 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.
Not 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.
Let’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.
So, is this we get documentation that explains the “WidgetMode” check box as “Enables WidgetMode”? No shit, really?
I’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.
If 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: 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.]
Molly - you hit it w/“Geek” to “English” translation.
As a PM w/no technical writers at my disposal, I’m figuring out how translate on the fly. I’m sure it’s just punishment for writing crappy specs initially.
I thought about delegating it to the geeks; but with English as a third language (to their original and VBA), delegation didn’t seem like an optimal solution.
So here I am. Googling blogs and hoping for pearls of wisdom.
I hate to be this pedantic, but, molly o’scribe, there’s no problem with the prepositionally-terminated clause you’re “correcting.” The sentence is not unclear in that fashion–it still possesses an object to which the preposition “from” refers. Your concern probably stems from the impossibility of ending a sentence with a preposition in Latin, but this is no reason for English writers to follow such a practice, unless they want to be purposefully Romantic.
Refer to the many usage notes listed here (for I can think of no more formal a source): http://dictionary.reference.com/browse/preposition
Let’s talk about let’s face it.
In IT, most people suck at their jobs. Believe it or not, even technical writers. Most work I have seen done by those in the technical writing trade has been generally inadequate and unnecessarily verbose. Dually, most engineers also write bad code and even worse documentation. But the fact of the matter is, that the reason all of you technical writers have so much crap to deal with is companies that do operate smoothly do not have a need to hire technical writers.
In my organization – a place where like all others things are very far from perfect – we do not hire technical writers. We instead have product and project documentation guide lines, function and technical specification reviews (of the show stopping nature) and as engineers run requirements gathering documentation in parallel to functional specifications drafting. The end result is a product that we know how it works, and how it works is documented. (There are legacy exceptions to the rule, but we do what we can when we have time to incrementally repair that).
And thus my point, since when engineers are good at their job and the engineering staff is lead by someone who is specification oriented, technical writers are rarely if ever necessary. Thus, technical writers are bound to hate their jobs – because they are called in to companies that have no clue how their product works, and don’t have anything that tells them, and don’t have time to iron it out. This criteria for requiring a technical writer leads you into the darkest deepest crud-holes of medium/large size companies world wide.