Hacker News Reader

Comment by nathan_long | Hacker News Reader

> I can spend time writing code or writing documentation.

You are selling yourself short. Your documentation the first thing people see. If it says "incomplete, confusing, and half-hearted", I'm going to hit the back button in about 15 seconds. I'm not going to spend 15 minutes reading your code to see if the first impression is wrong unless I think there's no viable alternative project.

Conversely, if your documentation is clear, thorough, and gives examples of usage, I'm likely to trust your project and dig deeper.

It's even been argued that writing the docs first helps you develop better: http://tom.preston-werner.com/2010/08/23/readme-driven-devel...

View on HN

I remember reading a story about Pages for Pages on NeXTSTEP. The manual was done before the software, so if there was any design question about how the program should work, they turned to the manual. I think it was an article by Bruce Webster (he is an awesome writer).

That's a code authoring technique I picked up from Code Complete.

It's useful for keeping your code in conformance with documentation. The problem is when the original spec turns out to be impossible (or difficult/expensive) to implement, and needs to be changed.

However if you doc then build, you've got a change control process that should accommodate this.

But the thing is that he is not selling himself at all. He writes some code for him and then maybe decides to release it as open source in case someone else finds it useful.

People who release undocumented code have no sense of social responsibility, and they are wasting everyone else's time.

The only way you can figure out if these releases do what you want is to spend half an hour trawling through the source code. Over the years I must have wasted weeks of productive time doing just that, and I can't believe I'm the only person who has.

I don't expect full API documentation and set of unit tests for every open source project - I'd be happy if most projects came with a short overview of how the code works, how it is implemented, maybe a couple of examples, and a list of its limitations. I do that for most projects I write for myself, to make it easier to come back to in a year or two when I next need to work on it.

If your project isn't worth spending an hour writing some basic documentation, then it isn't worth releasing.

Reply on news.ycombinator.com