4 ms·

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 th

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.

jvanderbot 4y ago
This is crazy. Documentation is indicative of bad design? Extensive docs, maybe. But simple docs and straightforward design go hand in hand.
- a1369209993 4y ago
  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.
  - als0 4y ago
    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.
    - TuringTest 4y ago
      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.
greendude29 4y ago
> 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.
faeriechangling 4y ago
Documentation is a hallmark of good design.

jvanderbot 4y ago

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

a1369209993 4y ago
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.
- als0 4y ago
  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.
  - TuringTest 4y ago
    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.

greendude29 4y ago

> 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.

faeriechangling 4y ago

Documentation is a hallmark of good design.