5 replies
by cynspencer
It's the elephant in the room, for sure.
I grew up in a government family and my dad was a mechanical engineer who not only invented machines, but had to draw them, then write papers about them and what they did. My mom was always editing his stuff; in high school, so did I. That's how becoming a technical writer started for me - and my dad always stressed how important it was to effectively document EVERYTHING.
Over the past few years, since the beginning of the dot-com explosion, I've worked at more than a handful of companies who didn't document anything - and it was my job to get things written down.
By nature, I've always gotten along well with engineer-types (having grown up with them) and I try to make the documentation process as painless as possible.
In my experience, working with younger engineers is a lot easier than ones my own age, at least from the documentation perspective. The "youngsters" seem more than willing to share information, and many of them are keeping notes of their own, as a necessity for knowing what the heck they've done, how to perform a procedure, and even comment their code as a piece of their personal processes.
Sad to say, but my constituents are frequently grumpy and eveny quite openly hostile when I ask them to meet with me to do "brain dumps" - even with plenty of advance notice! I've even recently played the "well, it's what I was hired to do - sorry that you don't want to deal with it, but you're preventing me from doing MY job..." In that particular case, I had to go to the boss and tell him the guy pretty much refused to help me, and that I needed his intervention to get my work done!
I'd love to hear from folks how you approach documentation - and why you hate and resist it so much - even when you know it is wholly imperative!
by fbuchan
Most of us in the industry don't hate documentation in general, but we instead dislike it when it is for its own sake. In many organizations, I have found when they do have documentation generated it is focused on the wrong things. In one (for the government in Ontario, Canada), I saw a documentation process that took seven times longer than the actual technical project. It focused so much on where every period was, what the structure was, and what the headings were, that by the time it was done it was a work of art -- and no longer relevant to the project it was intended to describe. After that experience, none of the team I had assembled would work for the same people again, because it was a draining and pointless experience. (The actual project was shelved after the documentation process, because it was no longer responsive to the need identified.)
Documentation needs to be relevant, focused and purposeful. The biggest challenge seem to be meeting that last criteria, because even when a good document is generated I have seen it frequently disappear into a file cabinet and never be reviewed, viewed or even made available in the future. As soon as that happens, even once, the people being asked to participate will refuse future requests as best they can. Why do work, only to have it not work for you in the future?
My personal approach to documentation is that the technical documentation has to be concise, but cover the scope -- and it has to meet the basic requirement that it remains relevant.
In code, I insist people who work for me write legible code that "requires" very little commentary. If your function name and parameters are well-written, your code doesn't require a description line that parrots them. Nor does the documentation require a paragraph for every function if the functionality is self-defining. When it is not -- and this is especially true in utility libraries that have broad purpose -- I insist at the very least there is some blurb that says how to use the function.
In the external documentation, I usually insist user guides are as clear as possible, with lots of images and as little text as is required to make the functionality clear. The only latitude on external documentation is when it comes to what I call "surface play." These are the documents that have no meaning to the technical process, but are some interface to the business process addressed. They should be as short and painless as possible, and if possible a single sentence can serve them. That latitude results from years of watching good documents on that surface simply be ignored. There is zero value in generating a paperweight.
My experience has also given me some insight into the relationship between the worker bees and the documentation bees. As soon as I hear the dreaded commentary about getting my work done, I hear alarm bells. The reason the resistance exists, right or wrong, is that the worker bees want to get what they see as their job done. The documentation bees need to recognize that a large part of their job is respecting that, and gently guiding the documentation along. As soon as it becomes imposed, it will fail at some level. If it is engendered with even begrudging support, it will eventually become easy.
by bschaettle
In some threatened industries, writing down what you know is often the first step toward unemployment. Being the sole possessor of key proprietary information gives you power and security. I know of many cases where older engineers have flat out refused to write down what they know about key products and systems, and were kept on payroll for their knowledge.
by billt174
I have no problem with documentation. My only issue is that the specs I'm usually given are poorly thought out and so any documentation I write is usually obsolete within 2 weeks. And who has time to re-write it multiple times. And most of the programmers I've worked with don't like to read. And of course why should I work my butt off to learn things and just hand it to someone who is not willing to make the same effort. This happens a lot.
by schellwork
Aside from the job security issues mentioned previously, one of the
problems of documentation is that sometimes you just know that it's
never going to be read (at least not by anyone who'd put the knowledge
contained within to good use). It will sit in a binder on a shelf, or
out on a network drive, where it will simply collect dust. Other times
your productivity will be unfairly compared to others who don't write
documentation (or do a poor job of it), and you'll suffer by
comparison.
Those issues aside, I find that if I start writing the documentation in
parallel with the development (rather than at the end) I can sometimes
catch those critical design assumptions before they're implemented
(when they're a lot easier to fix), and that may well pay for the time
spent in documenting the project.
This discussion is closed to new replies.
Trending After Hours posts
Sort by Trending