Hacker News Reader

> There is value in providing good defaults, but users will and should be encouraged to go beyond them. That's what the documentation is for.

While the original article does not state this directly, it is implied that he's talking about programs where you have to read the manual to be able to use even its most basic functionality. Right now, I want to get a job done. Exploring can come later when I've got time for it.

> Being frustrated is also normal. It's a natural part of the learning process.

It's part of the learning process when you're breaking ground. It's not appropriate when you're trodding the well-worn path. If your users have to resort to SO questions just to do common case things, you've failed them.

> I don't think it justifies turning everything into unconfigurable featureless appliances or not writing documentation.

He is recommending neither.

The author explicitly states:

    If you think that your application really requires documentation, it’s too
    complicated, and it’s going to make your users frustrated.

Additionally, the author says:

    If you compare the experience of using both coffee machines, even if the
    [simpler] doesn’t give you the exact kind of coffee you want, you are still far
    better off.

The author is explicitly saying that tools should not require documentation, and that ease of making a choice is preferable to the potentially better outcomes of a more complex choice.

I believe that neither are absolutely true.

There is no mystery as to why these open source applications do what they do. They don't because either they can't know what you want them to do, or we programmers haven't made the appropriate changes so they handle the cases where the program can infer what the user wants.

Side note: If this post does anything, I hope it's to get someone to submit a pull request to NVM so it prints better help messages during first use (like suggesting setting up a default alias).

I think the author is deeply wrong if they think there is "One KIND" of users.

Depends on the product category, target users, what your product actually does and how it differentiates with the rest, etc, there's a bunch of different variables to consider before sending a blanket statement that's so obviously false in many situations.

* she

Being frustrated is also normal. It's a natural part of the learning process.

I think the author's point is software that isn't frustrating beats software that is frustrating. He provides multiple good examples of bad error messages in actual software and how to improve them.

I'll admit coffee machine metaphor isn't a great metaphor, because his blog post is actually advocating configurability, but with a UI optimized for beginners and intelligent defaults (like a microwave with a popcorn button). I wouldn't get distracted by the metaphor.

But the popcorn button is notorious for making shitty popcorn. If the user were to rtfm, he would know to wait 3 seconds between pops and stop it. Or read a cookbook and make superior and far healthier popcorn on the stove.

Point being, one touch instructionless operation results in shitty outcomes.

I think the point is that it's the developer's job to make their one touch instructionless operation not result in shitty outcomes. The fact that my best option for Babel is to not update it because it already works and updating it will guarantee that it won't work is a fault of the author. Just like the fact that the popcorn button doesn't make popcorn well is GE's fault. That doesn't mean good software shouldn't work that way, it just means the current software is made poorly.

Extending the popcorn button thought, the popcorn function doesn't suck because the engineer is an idiot it sucks because its legitimately unreasonably hard to make a popcorn function that actually works and if it were feasible at all would add ridiculously to the cost and complexity of the microwave.

Since its unreasonable to make a reasonably optimal popcorn button it would actually be simpler and better to give the user more controls so they can make popcorn manually by setting the power level and time and starting and stopping it manually.

> ... turning everything into unconfigurable featureless appliances ...

The author suggests pre-configuring whenever possible, not abandoning configurability.

> ... not writing documentation.

She isn't suggesting documentation not be written. The implication is that if users are expected to read our documentation, then we could probably do a better job designing how our tool is meant to be used.

It's a warning against using documentation as a crutch to hold up poorly-designed interfaces.

> There is value in providing good defaults, but users will and should be encouraged to go beyond them. That's what the documentation is for. >Being frustrated is also normal. It's a natural part of the learning process. If everyone was always expecting everything to "just work" and gave up the moment they encountered the smallest bit of frustration, nothing would ever get done.

Sorry but this is a backwards way of thinking about the usability of APIs and tools. User experience is critical, even if that user is a developer. The lower the friction the more adoption and productivity will exist with your project. User experience isn't only a "front end" thing and all developers really need to think about this when designing APIs and software in general.

If you produce something that can't be reasonably executed with just a couple of steps you have failed. You should NOT feel frustrated just trying to start something. That is not part of the learning process.

Couple points your comment made me think of,

In some cases bad documentation can be worse then no documentation at all. If you find yourself here, improve your app and your documentation.

In some cases too much documentation can be a hindrance as it becomes hard to find specific pieces of information that cover > 90% of use cases. Consider simplifying and improving your documentation if you are here.

Finally, documentation without context is usually really bad. If your maintaining a popular web framework understand that many of your users may be beginners and write documentation accordingly. If your software caters to a super small niche of "experienced" users you should write it for them as well.

TLDR; don't stop writing documentation, write better documentation.

But honestly, as a software developer, if documentation wasn't the bane of my existence, something else would fill the void. And I'm scared of what that something else might be.

Couldn't agree more. We make a very complicated product that accomplishes a very complicated task. There are 100% use cases where an app should 'just work' and where documentation isn't necessary.

Of course, there are cases where deep configuration is required and including all necessary information in the UI is hopelessly impossible. For these cases - documentation is king.