Hacker News Reader

Comment by bluetomcat | Hacker News Reader

"High-documentation" isn't the cure, either. Just write quality software with well-defined interfaces, minimal dependencies and smooth building processes. I want to be able to build the thing without frustration, to start playing with it in order to learn its internals and debug it. Only then can I be comfortable enough to start implementing features and changes.

View on HN

"Just write quality software"

That's quite a load-bearing "just" there.

IMO, "quality" is going to be the sticking point.

No problem, we just need to hold a few meetings to define what counts as “quality”, and write it down in some good documentation.

It's devastating to learn after more than 20 years in the industry that the secret is "Just write quality software with well-defined interfaces, minimal dependencies and smooth building processes". If I and my colleagues had known only sooner about this straightforward and actionable advice...

That’s how I often use documentation - start documenting something, then ask myself “should the code be fixed to avoid the need to document this part? Yes, yes it should”.

A long provisioning instruction became much shorter as a result of automating it by reducing the need to document.

Are you pitching less documentation or none? It doesn’t seem like codebases are better when the architecture is unwritten.

As little as feasible, but no less than that.

Reply on news.ycombinator.com