Hacker News Reader

Comment by drewcoo | Hacker News Reader

Documentation, when it exists, is usually a band-aid covering up bad design. Pretty documentation seems like lipstick on a pig.

I would love a doc framework that was structured in a way to expose that and shame bad design. "How to FOO because we couldn't manage to make it easy for you" and "3 ways to work around our BAR" would be wonderful help topics. Topics indexed by known problem with the software. Etc.

Diátaxis could be used that way, but is not necessarily a forcing function.

And as far as user-friendly, I'm pretty sure users would appreciate the honesty.

View on HN

> Documentation, when it exists, is usually a band-aid covering up bad design. Pretty documentation seems like lipstick on a pig.

The above two ideas are incongruent, but anyway, you do realize that system design can't be self-evident for complex systems? How for example would you have no documentation for the Linux kernel?

Either you're mis-communicating your point or not thinking of anything larger than tiny systems.

This is crazy. Documentation is indicative of bad design? Extensive docs, maybe. But simple docs and straightforward design go hand in hand.

Not quite; rather, much like comments, needing documentation is indicative of bad design. The general ordering (better to worse) for this phenomenon is:

don't need, don't have > need it, have it >> need it but don't have it

"don't need it, but have it anyway" can be better than don't-and-don't, but that varies depending on the quality of the documentation.

Makes me think of “Everything should be made as simple as possible, but not simpler” by Einstein. There’s a limit to how much complexity a good design can hide. Complex software that come to mine are package managers, disk partitioners, security software, container managers, and so on…they really need documentation.

This. Developers tend to assume that users are expert in the field domain, and that they'll know everything that happens to the application when they use its controls.

But not all users are well-versed on the purpose and possibilities of the tool, so documentation should at the very least give an overall view of those. And even experts need to read about the vocabulary, peculiarities and assumptions of how the tool works in that field domain.

Some of those explanation may be taught in-app through explanatory text and step-by-step guides (which are forms of documentation), but for tools more complex than a trivial phone app, documentation explaining the tool and detailing its primary workflows and use cases is a necessity.

Documentation is a hallmark of good design.

Reply on news.ycombinator.com