A rant about application configuration
robotlolita.me
robotlolita.me
Documentation is terrible for applications. If you think that your application really requires documentation, it’s too complicated, and it’s going to make your users frustrated.
I strongly disagree. 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.
That said, although there is a lot of superfluous complexity in software today (dependencies are mostly responsible), I don't think it justifies turning everything into unconfigurable featureless appliances or not writing documentation. General-purpose computers are immensely flexible and powerful, and if we want them to remain that way, I think it's well worth putting in the effort to learn. The culture of instant gratification that seems so prevalent today may become counterproductive in the long term.
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.
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.
Point being, one touch instructionless operation results in shitty outcomes.
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.
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.
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.
If you think that your application really requires documentation, it’s too
complicated, and it’s going to make your users frustrated.
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.
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).
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.
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.
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.
Gulp was much much worse. Nothing worked at all out of the box and months later I still hadn't found the patience to get everything working right. Documentation was next to non-existent and there were points where I wanted to rip my hair out trying to work around "vinyl source streams", whether I needed a buffer or not, how to wrap a regular stream, how to get live reload to work, figure out why they had "blacklisted" popular modules that just made it easy to plug things in. At least it was fast but I never did get it working for some of the things I wanted to do and fell back on grunt sometimes.
Webpack is somewhat better I suppose but at this point I'm just prepared to be disillusioned every time I try some new javascript package which has maybe nulled the pain to some extent.
It isn't even that doing this stuff would be that difficult it's just that the docs are usually wrong, missing, incompatible, or outdated. No one bothers to fix them because by the time they do the JS community has just chugged along to the next "framework" leaving a trail of broken and abandoned projects in its wake.
I don't give a damn about bloat and modularity. Most of the time I'm just looking for a quick solution. If I have to download a big package so be it. Do everyone a favor and package things together that are compatible and work together so I don't have to spend hours tracking down the proper module for doing something like compiling sass and then another hour figuring out how to configure it and insert it into the build tool.
If I wanted to work on build tools then I would work on build tools but I get so tired of doing this stuff each time I need to set something up. In theory it sounds nice for there to be a million ways of getting something done but in practice I think it's just easier for someone to set a precedent for doing it one way and then have the community work on incremental improvements to that one way of doing things. This eliminates a load of confusion, incompatibility, and excess work.
All this might be an unpopular opinion but when I'm working on a project I like to direct my time towards the project, not the supporting development tools.
Grunt and Gulp make building slightly easier. Slightly. That's really it honestly. In fact my build scripts look very, very similar to what a Gruntfile.js file looks like.
Make just needs executables. It doesn't need specific plugins for each compiler. Its syntax is arcane but it was much easier to make it up and running.
Sure, a home user doesn't want that high-end coffee machine. But a professional Maker Of Coffee does; that's a tiny cut-down example of what you'll find in pretty much any coffee shop you visit, being used to crank out at least a dozen different drinks multiple times a day.
Or compare a kid's first toolbox to a fully-equipped carpenter's workshop full of power tools. Those power tools can rip through raw materials a lot faster than hand-powered ones, and can also rip through your flesh if you're not careful; they come with manuals, there are safety precautions you need to learn to use them.
That said it is certainly nice to:
- have all the configuration switches for your app in one place (a story: I've been using Adobe Illustrator regularly since 2000; it wasn't until like 2010 that I accidentally double-clicked on the pencil tool and found out that it has settings that don't live in the main 'preferences' window. Its defaults are IMHO terrible and made it a useless joke of a tool; once I'd found that it has settings it suddenly became the way I draw 90% of the shapes that make up my art.)
- have sensible defaults (see above parenthetical story)
- make your app easy to get running, which a hell of a lot of programmer tools certainly are not.
The workshop analogy builds on a false premise of low configuration equating to underpowered function. A pro will use a lot of different speciality tools that have no or minimal configuration, vs. a Swiss Army Knife that is mediocre at everything. In the same way, Unix-style workflows are very "shoot yourself in the foot" stuff, but formal configuration of each tool is minimal.
The best thing a complex application can do is be a general-purpose programming API at its core, with common workflows surfaced as a polished, simpified UI. Each of those workflows is its own application, with internal developer documentation to orient someone who wants to hack on it. Then the 80% cases are solved by default, and the 99% cases("this thing doesn't let me configure x") are solved by copy-pasting the application code and modifying a single line based on a Stack Overflow answer. And everything beyond that, you had to code anyway, so you enjoy a real programming environment with documentation instead, and hopefully a hook into the broader ecosystem so that the API is available throughout different coding environments.
Sadly, almost no application intentionally evolves in this way.
It's extremely flexible and allows you to arbitrarily build new commands that are easy to use. I automated a workflow for a drafting studio I worked at in 1989 and reduced the time taken to complete a drawing from three days to three hours just by writing new LISP commands for all of the most common things we did and wiring them up to the menu on the tablets we had.
Nowhere. According to the rubric set out here, there are no such things. They aren't applications at all. They're something else, something different, and compilers should be just as simple as Fart Noise Maker 3000.
The idea that "professional-level applications" (whatever those are) should be shipped in a non-working state is absurd. The fact that Fart Noise Maker 3000 should should be shipped in a non-working state is equally absurd.
Seriously, if I updated Babel and it suddenly was broken, I would have said, "Fuck this shit," and deleted it. There's just no point even trying to figure it out. The previous version worked, and life is too short to deal with this type of stuff.
But according to this rubric, I can and should expect things to Just Work. Does this mean I should expect pgbouncer to automagically discover what server it is to be pooling over, and that if it doesn't it's broken?
It's silly. Real tools are often more complex than drool-proof iOS Apps. We do ourselves a grave disservice by pretending otherwise - or even by pretending that this is desirable.
I've been working with logstash a bit lately and... oh my god. The documentation is outdated, the initial examples have examples without explaining core principles, the log messages are almost useless, it takes about five seconds for the damn thing to even /check if the config is valid/ and holy mother of god if I see another line saying that something's been deprecated..... Also for the love of said god, when a bug report is filed and the dev needs to explain in multiple paragraphs why something undocumented is actually feature, not a bug... there's something truly awful. https://logstash.jira.com/browse/LOGSTASH-1348
I can understand how these things happen, I truly do. But for something as widely used as logstash? No! Bad devs!
The simple fact that folks on stack overflow recommend to use two different grok creation tools to get logstash working properly (unless deprecation, because hey why not) is a complete and utter failure in my eyes.
Also, while I'm at it. I worked for an HFT firm that started going towards the devops stack, which required an install of Logstash. Installed it everywhere... I got woken up the next morning that every single machine was running cripplingly slow and that the trade desk had to cancel all orders. Huh. I installed it, but I never actually configured any of it to run...
Welp. A ps showed that logstash-web was running..... but with a 5 second uptime?
Turns out logstash-web's configs come installed with a bad config file that caused it to RESTART OVER AND OVER AND OVER. It killed any core the start job was running on for a good 10 seconds and immediately came up on the next. How...... why.... no..... :(
Thanks, Logstash. I seriously hope somebody from your team reads this article. You're in absolute desperate need of usability lessons.
/rant
I agree with the javascript examples; I had an even worse experience trying to set up a LAMP stack back as a teenager. It was a perfect storm of new problems and vague errors (which .conf file on my hard drive represents what's running on port 80? Did I screw up permissions? Is there something wrong in my php.ini? Did I install php as a module or a library? All I get is a timeout...). Today I know all the exact commands to debug the setup, but I wasted so many hours back then blindly struggling with something that could have been explained in minutes by more experienced people / software.
If you hear about Linux and want to install it, for example, Googling "Linux" just takes you to the linux.com homepage. Last I checked, it contained no links to distros. This is the same situation. Someone's goal is to install a Linux distro or to use nvm, so you should make it easy for them to install a Linux distro or use nvm. Don't make people wade through complex instructions for a process that should be simple.
Most software solves problems. Why add complexity when someone wants to get something else done?
(ed: I'm more intrigued than anything. It's a good re-titling IMO--I'm not sure who did it or why, but it's something I might've chosen if I didn't think choosing anything other than the post title was frowned upon. hope this doesn't distract from the actual post).
Original Title: No, I Don't Want To Configure Your App!
Hacker News Title: Don't Configure Applications Please don't do things to make titles stand out, like
using uppercase or exclamation points
Otherwise please use the original title, unless it is
misleading or linkbait.
Not saying I necessarily agree with the new title, but it is milder, and I think that in general moving away from clickbait titles is a good thing. There's enough clickbait junk going around the rest of the internet, having at least some standards at HN is fine.
And honestly, I find such a bold statement as "Don't Configure" to be more click-baity than the original title.
mkdir doesn't, for example, explicitly demand permissions with which to create a folder (but you can do that: mkdir -m 777 dirname). less doesn't require you to tell it whether to squeeze consecutive blank lines into one (but you can: less --squeeze-blank-lines).
It's especially sad to see JS community forgo this principle, since it seems to embrace modularity (as in "one module that does one thing well") so much. Babel 6 and Webpack could've been so much more fun to use if they came with sane configs out of the box.
That seems pretty cut and dried to me.
> They’re like the coffee machine on the office: you press the button, delicious coffee magically appears in your cup
But even office coffee machines usually have some level of configurability, in terms of serving size, flavor, etc.
For example, a newly installed browser on a machine that has never had a browser cannot read your mind to figure out your home page. It can run and do its job, but without a URL, and a default home page, it can just display an empty window.
(Some inputs cannot reasonably be made configurations. Should a ssh program connect to some particular host if run with no arguments? Maybe. Should "rm" have a default file name to remove if none is supplied? Crazy!)
Configurations are necessary, though. There are otherwise too many inputs. What's the answer? "I don't like programs that take many inputs; don't make such programs?" That's just dumb. Some functions simply don't decompose. You can't take every program that has 60 inputs and make it into 6 completely independent programs that have 10 inputs to somehow do the same job. If it can be done, maybe it should, sure.
Of course, nobody should be required, before using a program, to configure a myriad preferences that can all be reasonably defaulted. That seems to be the point of this blog, which is largely self-evident.
That's your example? Browsers have been doing better than that for decades.
> If you compare the experience of using both coffee machines, even if the former doesn’t give you the exact kind of coffee you want, you are still far better off.
Nope. Probably true for people that don't care about coffee, but give me the full espresso machine any time.
I wonder if pro coffee machine technicians prefer single-button full autos. Would make sense.
That sweet spot when you know just enough to be dangerous... Dunning-Kruger and all.
Combined with a conformist, non-confrontational PC culture where the loudest voice wins, this phenomenon can easily lead to suboptimal outcomes. At least short-term -- for long-term fitness, young foolish blood is vital :)
I definitely like that everything is configurable, but between 5 or 6 config files and dotfiles, there are hundreds of different options that are exposed that make my build/run phase operate slightly (or something vastly) differently. That's pretty overwhelming sometimes.
For example, the problems had with NVM are nearly all explained by reading the README[0] which on my laptop is ~6 screens of medium size text. If perused, it would explain how to install versions of node, how to enable different version, and how to set default global versions.
Now, the question is "why is it the case that tools aren't expected to be as simple to use as apps?" I believe the answer is because anticipating and guiding a user through learning that tool takes a ton of time and energy, much more time and energy than your average open source developer has. Additionally, it's incredibly easy to break things like automation of command line tools in an effort to cleverly anticipate and guide a user.
Most importantly, I'd like to remind everyone that this is open source software and you are more than welcome to attempt to change it. For example, NVM is a ~2000 line bash script; making some of the simpler changes you bring up (such as improved help messages and suggestions) is well within the grasp of a single person with an afternoon.
I don't mean to dismiss the author's points: the software mentioned is frequently frustrating to use, and can be extremely unhelpful. I've struggled with nearly all the same ones brought up in this post. However, it's not as though these where tools designed by Apple for the everyman; they where built by engineers under time pressures with an intended audience of other engineers, and if you think they should be different you are welcome to bring that change.
Firstly the distinction between library and application less important than he supposes. In the case of something like Babel, it can be both. There are just two interfaces to the same functionality. The errors he saw with Babel are obviously bad, but that seems to be a symptom of implementation.
Dropping configuration in favor of convention is a dangerous suggestion. Magic is great until it breaks, and when that happens you've created an opaque mess for the end user. I still have configuration, it's just implicit, undocumented, and spread throughout my environment.
E.g. you hit an exception that should have never popped up. Does it read badly? Oh well of course it does, because nobody who could have written it more clearly knew it was even possible to pop up in this instance. He might have even tested your scenario, but his system package xyz wasn't in version 13.4.12 as yours, but in 13.4.12b, so in his context it worked. You can minimize these things, but you can't completely make them go away. Even make them go away most of the time is often too expensive. You can of course also choose to invest $500k every year into Babel to increase their testing, but I certainly wouldn't, just to make a few exceptions more readable.
And in fact, if you tracked down from all the context variables why it failed in your context, you will actually find out that you can track down the change to an issue and a developer and you can discuss with them how in that case a better exception can be printed, how the code may need to be changed to consider the context you are providing etc.
Nothing of this is done better when reading usability guidelines. Just as well as you and me people mostly know what is good and what is bad. They don't need teaching in that.
The thing that can be really done is always try harder in your code (when was the last time you looked into the docs/source of a lib function you use and catch the exceptions that function can throw, handle some of them and raise more readable exceptions for the once you can't handle?). Secondly, when you hit such a situation you can spend the time to track down the error to its core, write a good issue about it, discuss with the responsible devs what to do and help implement the solution (have you looked at the underlying library functions, caught their exceptions... oh, you know what I mean, right? People often don't do that part). Last but not least when one has done that often enough to be good at it, to spend time and energy to help some noobs to do the same (and teach them how to read the underlying library functions).
This is an unnecessarily rude assumption. Even the most rudimentary glance at the author's Github page, linked at the bottom of their blog, would have shown you that the author has created and contributed to multiple popular applications and libraries.
In that regard I hope I can make clear why it is not necessarily rude to tell someone that they haven't made the experience. I have certain assumptions about climbing mountains, but I have never done that so quite a few of these assumptions will be wrong or not about the actual points you have to deal with while climbing. I need to be aware of that, though. Otherwise I will a) think that I know everything there is to know about that topic and b) I will think I can give advice to other people how they should do it.
"I need the user's database credentials" -- cool, find them in this convenient spot anyone can hack!
"I need the user's facebook and google api keys" -- cool, find them in this convenient spot anyone can access!
Obviously, what is needed is an OS-level keychain that can be accessed by the installer. I wonder if anything like that exists... ;-)
It would be awesome if the user could be walked through creating all the external accounts, apps and api keys if the external service doesn't provide an API for this. If it does, then hopefully it provides an oAuth flow for it.
Come to think of it, everything should just be an oAuth flow :)
Are you targeting Edge 13 or Chrome 49? Great you only need to compile out a few features. Are you targeting IE 8? Well, better compile everything. Unless Babel is to assume the whole world is uniformly stuck at ES5, it simply can't pick a good default.
It certainly baits more people into response than a moderate argument but I'd rather see that version than see other programmers cite this one as a reason to document nothing. That's much worse.
If you tell someone who thinks the sky is blue that it's red, then they'll end up believing it's purple. If you try to convince them that it's purple, though, then they'll probably think it's far closer to blue than you meant. If you want them to see the sky as purple, then you have to insist it's red.
It's sort of a Red Queen problem: people know others use hyperbole and absolutes to make rhetorical points. So, when listening to an argument, people internally temper every point they hear to "remove" the rhetorical effect. Thus, when trying to make a point, you need the hyperbole and absolutes—because even without them, people will still assume they're there anyway, and "temper" your point into nothingness.
This isn't to say that personal opinions need to be expressed in such absolutist terms to have impact, though. When you're giving your opinion, you're just telling people where you are on the spectrum. A reader can pretty easily tell—usually from the different writing style—what's rhetoric and what's personal thought; and while people engage with (i.e. debate with) rhetoric, they compare themselves to opinion. When I say "I think the sky is purple", that's not an argument; that's a way of letting you know that if you think the sky is purple too, you've got someone to discuss that with.
HN seems to really like anecdote-rich "humble" presentations of (opinionated!) personal experience, but the persuasive essay has an important place as well. For every Folklore.org, there's a Unix Hater's Handbook. And although Folklore.org is certainly entertaining, I've never really seen a productive debate stem from a post there—certainly never anything that inspired someone to code up a new project to prove their point.
(Got myself burned with Babel6, too)
If you write your web back-end in C/SQL its likely that it will run unchanged for the next couple decades.
If you write your web back-end in PHP, it will probably run with only minor changes for the next 5-10 years.
If you write your web back-end in node.js, you will be lucky if it runs without modification in 6 months.
Just because something is cool, or easy and fast to bootstrap doesn't make it the best choice for a long term successful project. Its like people used to say about delphi vs visual basic, "Delphi makes the easy stuff easier, and the hard stuff doable. Visual basic does the easy stuff for you, but makes the hard stuff impossible." I think that applies to a huge number of recent "technologies". Careful use of make, RPM/deb and kickstart will solve all the same problems as $COOL_NEW_TECHNOLOGY. It might take a little longer up front, but 5 years down the line when your project is a million lines of code across multiple platforms and languages with differing dependency tree's/etc you will be thankful you didn't tie yourself to a build environment designed for a particular language/enviroment. Especially, if said technology gets abandoned and you end up maintaining it in-house.
But yeah in node land if you don't upgrade to the latest major you're going to be left behind in bug and security fixes (good luck finding projects with actually maintained LTS branches and if they exist they're almost always the previous major version and nothing further back).
... What is this supposed to mean in 2016?
Yet ANOTHER needless title edit by HN moderators. Seriously? stop editing the titles! Not only do you suck at editing them and often butcher the original meaning and intent, but it's totally unnecessary and adds ZERO value. Meanwhile, I have to bring it up that you butchered the title, which detracts the comments from the actual discussion.
Just stop.
Edit: is there any statistics for how often HN titles are different from their actual articles? Maybe some analysis for how often they changed the tone or meaning too. Could be a fun little project for someone.
The article title is obvious linkbait, so changing it was called for by the HN guidelines. People sometimes mistakenly think that the guidelines ask for the original title to always be used, but that's not so: see https://news.ycombinator.com/newsguidelines.html.
In this case the procedure we followed is almost a technical one. First, take out the obvious linkbait: "no" and "your". That leaves "I don't want to configure app[s]", and that's misleading, since the article is not about a personal desire but rather a critique in general of applications that require configuration. "Don't configure applications" seemed as close to that as one could get without being either misleading or linkbait. Think of it as dropping a perpendicular from the point of the original title to the HN guideline.
But that's not to say we got it right in this case, let alone always get it right. When we do a bad job of a title, a good way to show that is by suggesting a better one, i.e. one that is more accurate and neutral. If you read HN often enough to be mad about title changes, you should be aware of how happily we accept better suggestions from users. Just please don't suggest a title that goes back to breaking the HN guidelines, since that's always the reason why we change them in the first place.
By the way, if you think we suck at editing titles, that is likely because you notice the cases you dislike while the others blend into the background. Everyone bats zero if you only count the strikes. I'm going to mark this subthread off topic now.
Edit: ok, let's try "A rant about application configuration" instead of "Don't configure applications".
This is what linkbait looks like: watch what these this kid can do with a keyboard! / 10 tips for a slimmer you! (you wont believe number 3!) / I saved $3000 a month on hosting with this one trick
Yes, I want you to be editing linkbait titles so they are actually descriptive and helpful to users. I am grateful for that thankless service. But this isn't linkbait. and another post you edited wasn't either. And it's REALLY annoying because in both cases it totally changed the meaning.
here is what I would suggest:
1) make it clear in the guidelines what linkbait is. I think that is not established.
2) make it clear when a title has been edited in the UI
3) when a title differs from it's original, cite the original, and explain the reason for the change.
4) only change it if you can really do a better job than the original title; or if someone else suggests something better. (better being: more descriptive of the contents). Err on the side of leaving it alone.
I'm happy to have conversations about this stuff, but can imagine little more soul-destroying than having to come up with a bureaucratic taxonomy of it and a punctilious rulebook to match. That wouldn't be in HN's spirit anyhow. This place has always been about having a small number of informal principles and interpreting them as best we can. The principles are long established; there's a reason why we change the site guidelines so rarely.
1. https://en.wikipedia.org/wiki/Misattribution_of_arousal. I originally wrote "mere proximity" but that was the wrong effect.
The other thing to consider before preserving unnecessarily clickbait-y titles is that leaving them intact could motivate enough readers to flag down the article entirely out of distaste for the title, resulting in more severe de facto "censorship" than you seem concerned about here.
.
[0] excluding, for the moment, arguments about articles from and regarding YC insiders like PG.
Even then, all it usually saves a phone user is a double tap to zoom into the article.
That's enough to get most "responsive" websites showing with no left margin at all, which looks fucking awful. Worse still, half the time I get a hamburger menu and mobile-style navigation!
Apologies for not adding anything to the conversation, I just had to rant about another web anti-pattern :(.
None of those errors are particularly cryptic and neither is that help for nvm. Don't be impatient