I haven't always been a writer (and some would argue I'm still not since I'm still not working on the great American novel). I came to appreciate the power of language later in life. So I can sympathize with the dread many developers feel when they have to write documentation. However, I've noticed lately that as a community our writing and documentation skills are noticeably dropping. Not a week goes by I have a meeting with developers who can't clearly explain what they are trying to do or why it is failing. Many well-written pieces of software have dismal documentation. Even finding poorly written articles in magazines and journals (present company excepted, of course) seems to be a more common occurrence. Case in point: I was reading a magazine last month -- I won't mention the name -- and there was an article about converting binary numbers to BCD. The author mentioned the technique converted hexadecimal numbers to BCD which isn't really accurate, but I could forgive that. That was the least of the problems, though. After reading the prose, I had no idea how the technique illustrated worked. Total confusion. Just to amuse myself, I tried writing code in C based on the description to see if it would work. Of course, it didn't. Finally I opened the assembly code provided with the article and studied it. I was able to generate the C code to match. It worked but there were several unnecessary extra steps included in the original code that I was able to remove. Overall, very sloppy. And its not just articles. I've recently been working with a vendor's "standard library" for a product. Its actually quite good, but the only documentation is automatically generated from comments in the code. That'd be great if the code were significantly commented. I've seen people use Javadoc or Doxygen to build great documentation. But just dumping out whatever comments you happen to have into a file doesn't substitute for documentation. Those tools are just that -- tools. They don't build documentation any more than a hammer builds a house. You can build a great house using a hammer, but the hammer really isn't the important part. So why is this? Is it a failure of the education system to teach communications and critical thinking? Is it our short attention span that can't get through a single tweet? Is it because shrinking budgets don't allow for documentation? Or am I just turning into a curmudgeon? I guess that's possible, but I don't think so. Granted, there are some great examples of documentation out there. PHP comes to mind. But even projects with great documentation sometime fall short in areas (try porting gcc to a new target). I try to subscribe to the golden rule. We are all programmers. We've all picked up code to maintain or a library to reuse that had great documentation. And we've all inherited code with lousy documentation. So we obviously can tell the difference. I figure if I write documentation that I would be happy to read I've done my job.

October 28, 2010
URL:http://www.drdobbs.com/architecture-and-design/the-sad-state-of-documentation/228700642

Terms of Service | Privacy Statement | Copyright © 2024 UBM Tech, All rights reserved.