We have a Synology server running at our house. It runs operating system which is called Disk Station Manager (DSM) which is heavily modified (read: locked up) Linux distribution with most of its parts configurable via web interface.
However, underneath there’s another, darker layer. The world of white text on black background. The world of terminals, command line and stupid wrappers for ordinary commands. And it is dark indeed and not because most terminals have dark color theme, but because you’re completely on your own there. Documentation for this part of DSM doesn’t exist, because why would a company like Synology bother with one.
Just to give you a taste: Bash completion shows that there are 274
commands which starting with syno prefix. They implement
which most prominent section is copyright notice. There’s not even a world of
explanation on what a particular command does4. But this isn’t the worst of
all, because Synology does far worse things to make our lifes miserable, like
replacing sshd with their own heavily modified version which forbids root and
non-admin logins, or constantly regenerating nginx configuration from
Mustache templates. They constantly screw up Unix file
permissions, heavily relying on Access Control Lists (ACL).
Anyway, all of this means that from time to time you’ll probably need help of people who figured Synology quirks out. These people exist, but usually they hide, so all you get are poor quality blog and forum posts.
One time I decided to move my docker containers from Synology Docker GUI to ordinary docker-compose, but I couldn’t figure out how to autostart the damn thing. The information on how to setup docker-compose on Synology wasn’t scarce, but all the forum and blog posts which I was finding had one thing in common: they focused on getting SSH access to the server, logging in and running docker-compose… once! Nothing I didn’t already knew!
Other time I was searchin about Zigbee2 integrations in Home
Assistant and found this one guy’s blog. He head beautiful setup so I thought
that he must know what he’s doing. The magic disappeared when I reached his
commands for installing a custom component. They were duplicated for Python 2
and 3 (just to be sure, I guess) and apparently
pip install was a Home
Assistant restart command. Sigh…
My wife once wanted to try a Linux program which she had to download from the
Github, compile and install/run. It was written in C and configured in the
ordinary oldschool autotools. So
./autogen.sh && ./configure && make. There
were clear instructions, with complete commands provided in the README of
this program. And my wife failed to follow them, although she typed the
commands letter-by-letter. Here comes the husband programmer. I had opened
the page, typed the commands, same as my wife and… everything worked.
Miracle? Not really. I subconciously made additional step before even running
autogen script: I had installed basic depndencies (build-essential) which I
knew were necessary and probably missing on a laptop of non-programmer. It
was easy, took me 5 minutes and my wife had probably wasted an hour or so,
banging her head against the wall.
Back to SSH, I’ve found this one guy on Synology forum who was genuinely scared to use it. He described his first successful login as stressful and scary. To this day I don’t understand why he was so afraid of it. Nevertheless, he became an eye-opener for me. Thanks to him I had a revelation: I have some very deeply ingrained skills. I don’t even think about them, they’re like breathing. Many other people probably don’t have these skills.
It’s a simple idea which grows pretty big when you think about it.
Don’t You Get It?
We explain things to other people pretty much all the time. We go deeper and deeper with our explenations and at some point we stop doing that. We must assume that our interlocutor has knowledge to understand the foundation of our explanations, and if these explanations are opinion-based, that he agrees with them. My guts tell me that unless you have the a-ha moment3, you can’t be sure about this assumption and at some point it will be wrong.
I like when people tell me that they don’t understand me. It helps both them and me: I’ll try to explain things clearer and they have another opportunity to follow the explenation. These people are minority. Most of us will remain silent because we don’t want to look dumb.
Even worse if you’re writing instructions, because you don’t know the entire future audience of the document you’re creating. In this case you have to assume some level of competence.
Explain Me Like I’m 5
What’s the point at which we stop going deeper? One might say that it depends on the audience, but sometimes we can’t easily say what is the audience. I’m writing blog posts and I think that they’re mostly geared toward developers, but maybe they’re not.
There’s this acronym: ELI5 which means Explain me like I’m 5 which means that the answer to the question should be as easy to follow as possible. I’m thinking that maybe we should assume that our audience is 5 year old all the time.
I was listening to The terminal as a platform episode of Changelog podcast. It was an interview with Will McGugan who’s behind Textual and Rich Python libraries. At one point the interviewers asked him about installing Textual applications.
I think that most Python developers are familiar with pip and its derivatives for installing Python code and that we consider using it quite straightforward. Yet the interviewers insisted on using a kind of app store for Textual apps. I wonder if this is the equivalent of ELI5 when it comes to installing applications.
Let’s think about it: there are so many things which can go wrong when we use pip to install Python applications. They don’t go wrong for me though, so I advertise this way of installing applications in my own software. But maybe it is wrong. Maybe I should consider another distribution model for my applications. Maybe I include pip in READMEs because I’m lazy and this is she simplest way to provide installation instructions.
I don’t see my 6 year old son using pip to install a Python app. At the same time he does’nt have the problem to browse Google Play Store on his mum’s phone and install the game with the most flashy (or Minecraft-like) icon. It certainly takes more time and skill to publish such applications and I certainly don’t see myself designing beautiful logos.
Acronyms (TODO: change this section title)
I like how The Economist approaches acronyms: unless it’s “USA” or “FBI”, there are no known acronyms. I try to use this method at work. I slowly explain everything, starting from the basics. I assume that the person I speak with have no previous knowledge on the topic.
I treat documentation similarily: readers know nothing. Recently I’ve been working on documenting our vast build/continuous integration/delivery system so the other people could get my document and do things which I do1. I started with description of… setting up a git. The only assumption is that reader knows what a terminal is a how to open it.
Maybe my company wants to fire me, I dunno. :) ↩
Zigbee is a low-power, wireless protocol which is often used for small devices (like sensors) used for home automation. ↩
A-ha moment is a moment when another person audibly gives you a hint that they understand what you’re saying. Usually they say something like “Oooooh, now I get it!”. ↩
syno_sed certainly doesn’t do what original sed does. ↩