Hacker News Reader

Comment by ivanyv | Hacker News Reader

I agree with most of his points, but let's be honest people, writing good documentation is no easy task. And not many programmers are good communicators either.

View on HN

Writing good code is both difficult and all about communication. If you can write good code, you're probably capable of writing good documentation (low level technical documentation in your native language, at any rate) if you really want to.

I kind of disagree. While I agree with your first statement somewhat, I know many programmers who can express themselves pretty well in their language of choice, but when it comes to human communication, well... ;-)

By "no easy task" he doesn't mean it's some kind of intractable problem. (Though it is much harder for some than others.) The problem is that it takes non-negotiable amounts of time. Writing is work.

Even if you're one of those rare people who can just sit down and type press-ready copy (cough Isaac Asimov cough) it takes time to physically type it all.

> If you can write good code, you're probably capable of writing good documentation

Indeed, but is that the best use of time for someone who can write good code?

http://en.wikipedia.org/wiki/Ricardo%27s_law

While it may be true that writing good documentation is not easy, writing bad documentation IS easy, so why do so many coders not even do that?

I write open source software for fun. No other reason. Your ability to use my software for stuff is a side benefit for you of this. Writing documentation is not fun. I don't want to fill my fun time with not fun activity. I will however take money for writing documentation (quality not guaranteed).

But I don't use your software. I use software written to be used. Web.py is written to be used. The developers want people to find it useful. Lighttpd is written to be used. Apache's software is written to be used. Ruby and Python are written to be used. Perl is written to be used. Yes, they may all be fun for the developers, but ultimately, they strive to be useful. I'm sure not every aspect of developing a major open source project like one of these is fun. I don't know anyone who finds debugging fun, for example. It has to be done though if you want to produce something useful (even if only to yourself). Documentation really should be done if you want to produce something useful to someone other than yourself... and even to yourself if there's any chance you'll leave it alone for years and then pick it up again.

You make a good point, however:

1. I have had many people become angry with my stance on documentation for MY projects (written with the above contraints, for fun, for me, if you want to use it: cool not my goal tho). That sort of entitlement ruins it for everyone.

2. It is still done for free, if you don't like the results offer compensation for your choice of improvement. If the work is all volunteer, some stuff that isn't fun won't be done. (debugging is more fun than documenting, since the former is required for something to work right). This is why most non-profits also include someone who is either paid or otherwise rewarded for doing the crap work.

Let's be blunt: Sturgeon's Law applies. Many coders are lazy and half-assed. They take little pride in their work.

This is why you see so many little aborted projects where someone lost interest after the first weekend of work. This is why you see defensive coders complaining about how people expect their "active" project to ever update again. For many of them, there's not much interest in offering a useful tool or collaborating to create better software; they just want the egoboo of saying they made a "project" out of some slapped-together code that never really needed to be in a public repository.

Even bad writing isn't really very easy. And bad documentation can make the situation worse. Why would anyone want to do that?

Good clean code is the best documentation.

It really isn't. Just like a well-designed city is not the best map or the best directions. If you asked someone for directions and they started explaining the entire layout of the city instead of just telling you where to go, would you say, "Thanks man, those were the best directions I've ever been given"? No, you'd probably ask someone else.

It's sort of a 'teach a man to fish' problem. If someone is standing on the corner of a hypothetical 14th Street, and if the layout was something like "the Streets run East-West, and the numbers go up as one goes North", it's probably worth their while to explain this. And if the city is designed such that all the avenues are alphabetical from East to West, I'd probably mention this as well.

Personally, I greatly prefer to receive directions that include some redundancy and background information. And yes, every now and then I think "Wow, those were great directions" when someone gives me an explanation that increases my knowledge beyond the narrow scope of my question.

Reply on news.ycombinator.com