Hacker Newsnew | past | comments | ask | show | jobs | submitlogin

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.




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: