Documentation? Again?

A year and a half ago I was already whining on the quality of documentation even of big companies. Since then the situation seems to get even worse!


I recently came upon this article - "Api Documentation" by Chris Parnin. The article is a research studying the fact that most developers are using StackOverflow as a main documentation source. I totally recommend to read the whole article, but here I'll just quote the main result of the study:

• Developers may be getting as much as 50% of their documentation from Stack Overflow.
• More examples can be found on Stack Overflow than the official documentation guide.
• In web searches, Stack Overflow questions are visited 2x-10x more often than official documentation.

Write-only code

There are lots of modern and mature languages stating the speed of coding as one of major language advantages:

Python lets you write the code you need, quickly. 

python.org

Perl -- Because life's too short to code without punctuation.

perl.org

Phrases like this always puzzle me. While it sounds nice to be able to write code quickly, what's about reading it? I mean, the code you write is not only for a compiler to read. The code is to be read by humans. By you! And by those unfortunates, who will have to support your code after you leave the building. These poor guys will be glad to know that the fancy language allowed you to write that shit of a code by 15 minutes faster. This warm thought would be with them all that hours they would spend sticking eyes into cryptic lines, trying to fix that little mistake you did 6 months ago..

Documentation?

Well, yes. Documentation. You know that you have to write it for your code, but you never write it, because it's soo boring. And when you have to deal with other's code, you blame them for not writing the documentation.

OK, all clear, next post please.

Well, if you are still here, that's what I wanted to say. There are many huge projects done by serious companies with lots of the documentation. And it's clear that they spent lots of time on documenting all and every public function. But still they are doing it in a wrong way! Lots of documentation is not great by itself!

Rewrite or not rewrite

When I first read Joel on "Things You Should Never Do", I thought that though he's mostly right, there are things that can be argued.. It was long ago and forgotten, until recently I've read "Why rewriting code can be startup suicide" article by Steve Blank and it reminded me of that matter. So here are my 2 cents.

In a perfectly designed world—one with no history—we would not have to suffer everything from hemorrhoids to cancer.

Neil Shubin

"Your inner fish"