There's nothing I hate more than text config files
Computer Science github Open Source · 8 comments · 750 words · read ~621 times.
I'm going to revisit an argument I had in… Ooooh… 2001ish? I wanted to make some edits to my university's fledging student union website. In order to do this, I needed to learn the arcane art of SSH. This was one of my first introductions to text based config files. I was horrified! A single typo, or a stray comma could break everything. The instructions our WebMaster provided were laughably unclear. Manually creating a config file - and getting it right - was a chore.
So I downloaded PuTTY and never looked back. It had a simple GUI. Well… simple enough. It was impossible to type an IP address into a box designed for a port number, it could tell that username was unlikely to contain a non-ASCII symbol, and that made it slightly easier to configure a connection.
The job of the computer is to do the hard work for us. Computers shouldn't recognise that we've made a mistake - they should stop us making mistakes in the first place!
Flash forward to today. I wanted to release an update to my NPM package of SuperTinyIcons - which are hosted on GitHub.
I figured that I'd have to click a link on GitHub, do the OAuth dance, click on a few GUI elements, and hit a big save button.
Nope!
I have to create YAML text files. Manually. Because it is the Year of Our Lord 2020 and computer engineering hasn't evolved since the earliest days of UNIX.
Don't get me wrong - I love the utility and versatility of the command line. I'll happily manually edit a JSON file in nano and use sed to update a bunch of documents. I rely on diff and grep daily. But when it comes to configuring things - I am undone. I don't want to learn whitespace rules just to get something working.
Let's take a simple example. Here's a snippet of YAML from the official guide to releasing NPM packages via GitHub:
jobs:
build:
runs-on: ubuntu-latestWhat are valid options for "runs-on"? Where would I find them? What are the differences between them? What happens if I spell something wrong?
Luckily, the GUI was invented to save us from ourselves:
M A G I C !
This goes for almost every element of the config file. If there are a set list of choices, present them to the user. If there is only one option, hide it. If there are two options, give them a checkbox.
The thing is, GitHub gets part of the way there. If you want to setup a webhook - you get a GUI. 
Why does one part of GitHub offer a user-friendly way to manage configuration, and another part only provide a user-hostile environment?
To make it worse… NPM IS OWNED BY GITHUB!
I'm not saying you can't have a text file. I'm not trying to take your toys away from you. Have a sudo mode which lets user hand-stitch a config together with butterflies and a binary keyboard. Go nuts! Want to store the config in git so you can see what changes have been made? Brilliant! To be explicitly clear - store the config in a text file. But have a GUI first, and expose the text file to any masochists who want to manually replace all the tabs with spaces.
I just can't be bothered reading 22 thousands words of YAML spec, a further two thousands words of GitHub instructions, and - no doubt - a hundred different StackOverflow questions, just to send data from one computer to another.
I heard someone say that part of Amazon's success was its relentless focus on convenience. How is manually creating fragile text files convenient for me?
We have to stop this fetishization of the text file as the primary method for configuring computers.
This is something @firebrickltd — a GUI for those who prefer to use a GUI, or text access, for those who prefer to edit that.
Or use both, for different things.
(And if you offer only a GUI, please ensure there’s a way to export the config: text is portable.)
Have you seen the Fish shell?🐟
To configure it, you run fish_config, it boots up local web server and gives you UI. When you hit save, it writes all the changes to the correct config files (which you can then tweak/override). Much nicer than fiddling with bash/zsh config.
Jon Ribbens says:
I'm not convinced. Your main issues here appear to be (a) YAML, and (b) poor documentation. YAML is indeed an appalling abomination that should be killed with fire. And a GUI won't save you from poor documentation (a pull-down saying your options for "foo" are "bar", "baz" or "quux" helps little if you've no way of knowing what those values mean or how to choose between them). GUIs are often worse than text configuration files, because they hide detail that you need to understand.
Nope. I'm using YAML in this example. I'd say the same things about JSON, or anything else.
Poor documentation is a problem for text files as well as GUIs. But at least a GUI tells you want fields are, and what valid options you can choose.
Martyn says:
It would imply that the author knew every possible value or was willing to continually track and update his creation as other projects introduced new options. In the example you chose, I'd expect the string to be compared against a similar string in the target platform. Implementing a selection box would potentially hinder adoption on different platforms. This option would likely end up as a freeform text field in any GUI, resulting in very little gain.
Providing a GUI also implies that the application is being configured somewhere that the GUI can be displayed. It may be 2020, but many servers are still handled remotely via the CLI, because it's generally sufficient for task at hand and an efficient use of resources on the target server and bandwidth.
Further more, the authors skill set or time available may not extend to developing a GUI and documenting the app. If the choice was between a configuration GUI with options, but no documentation to tell you what they meant and no GUI, but sufficient documentation to allow you to take a stab at configuring in a text file, which one would you choose?
In the specific case above, we're talking about GitHub services running on GitHub's hardware. They know what is available. If your command-line utility can't tell you what options are available, it is broken.
Providing a GUI doesn't imply that only a GUI can be used. As I said above. Store the resultant file as text, json, xml, yml, or whatever. Let people edit it via SSH if they want. But give people the option of a modern GUI.
Your last point... Most open source software is poorly documented. Even GitHub's documentation for their text based tools is terrible. The Alexa documentation is similarly awful. But a GUI gives discoverability in a way that an empty text file doesn't.
Look, if the config file said:
Then I'd be able to use it almost as easily as a GUI. But almost no one does that.
Isabel says:
If there are two options that are mutually exclusive, give them radiobuttons.
Dave says:
Everything to do with microservices and docker uses these YAML files and it's terribly confusing! And then they change the schema from version to version, so there's another headache. This is not NPM's fault though, it's GH actions I think you're dealing with. You can publish to NPM via command line (npm publish, once logged in) . But I prefer also using CI builds to run tests etc before publishing to be safe.. I use circleci which uses the same yaml config stuff, but at least I found the documentation to be good.