Teman
The good tech writers I knew used an audio recorder for step 8.
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.
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.
Scott, just to clarify, technical writers are not needed to interpret documentation for internal use. The documents they write are for shipping with the product. Hence, these documents are supposed to make the end users (advanced, intermediate, basic) comfortable with the product that is bought. Be it a developer, manager, or Jesus, he still is essaying the role of a product/technical documentation specialist by interpreting the product to the user. There is no such thing as a Technical Writer, it is only a role one essays.
sample softwaretechnical documentation
I completely agree, exept I would probably be getting just as mad as the engineer.
Technical writing is a real job, and one that demands research skills. You do what is necessary. If you don’t know the product, you play with it until you do know. If you can ask someone, do, but as another writer here pointed out, you should have some information in advance or you’ll just overwhelm them. The best technical writers are the ones who are very organized and methodical in their research, and then translate that naturally into language.
Well, talking about my experience as a technical writer, i found that you can really write a help document just by exploring the program yourself if the program not that difficult. But, if the project’s level is high to be easily understood, i think it will be better either to start reading document analysis or any docukent related to the software, or you might sit with the developers and start to understand from them every single details in order to know how you will address the audiences.
Life’s a lot easier if I don’t have to deal with the engineer. I usually get all the available documentation–requirements, design, UAT, etc.–and then check the current application build and figure out how it actually works.
I’m a technical writer for very complex server/client networked products and there’s often no way I can sit down and see the whole system work because 1) they never give me a whole system to play with, and 2) it’s too complex to start out with nothing to read first. The engineers are no better off; each writes his or her own piece and sometimes has no clue how the other plug-ins or components use the data down the line. But that’s not as bad as the fact that often, when I ask, “So when would I customer use this feature, and what for?”, I get “I don’t know. I was told to build a [blahblah] service to handle [IETF spec] protocol…”
I envy tech writers who do refrigerator user guides…
Scott S. McCoy wrote, “Most work I have seen done by those in the technical writing trade has been generally inadequate and unnecessarily verbose.”
Scott, I’m a technical writer in the software industry. Unfortunately, I have to agree to some extent with you. Unlike other professions, technical writing is not regulated, and enforcement of standards is not possible. Some ‘technical writers’ leave much to be desired. On the other hand, look around, and you will find some excellent tech writers.
I disagree with Sandeep, who wrote, “Tech writers looking for developers/engineers for help are kidding none but themselves…” These people love talking about their work, in my experience. Usually, they are extremely busy people, and if managers do no allocate time for them to interact with the tech writers, the time they do spend will be in addition to their other duties.
Wes James highlighted a common problem with documenting complex software. Everyone knows his or her bit in detail, but not the whole picture. Often, I find that different people give me conflicting information. That’s where technical writers add significant value to a company–we ensure that the ‘story’ that the end users receive is complete and consistent.
That make sense. Developer like me would be proud to see that documentation.
Documentation is used here to mean hard copy, online documents, online help, quick start guides, and other written instructional information. The need for documentation is often an afterthought when designing products. Product development engineers are so enmeshed in creating the product that they feel its use is intuitive or self-evident. This assumption is usually not the case. In many respects, documentation compensates for the lack of intuition. It permits understanding the product and provides a quick source for looking up specific details that are not immediately obvious to the user.
Let’s face it - no one reads technical writing unless they have to!
A good tech writer starts by being a busybody and an eavesdropper. I consider it a good day if at the end of the day, during the information gathering phase of the project, my feet hurt, and my conputer is cold. Take an engineer (or two) to lunch. Find the most egotistical one of the bunch, get his/her thoughts on the projects overall, the players, and management, and drill down from there. I’ve seen too many tech writers sit on their rumps waiting for information to be tossed to them, or whining because they “have to” play with the software themselves.
Technical writers are, in a sense, teachers. You’re teaching not only yourself but your readers about the product.
Technical Writing is not rocket science nor will it ever become rocket science. It requires a great amount of patience, endurance, perseverance, and initiative on the part of the writer, but ultimately it can be done. Like I always say “mind over matter”. Welcome to the real world, and indeed Tech Writing is part of the real world!
