Documentation and bad software. Unrelated.

I always felt, and seriously believed that I have bad memory. Albeit, bad memory when it’s convenient to me, as some have accused but I say those accusations are baseless and defamative . Anyhow, I think I do not fall above average when it’s about memory. I have probably never been the brightest student in a class.

Ironically, one of my oldest memories is telling my father that I don’t have good enough memory compared to my class mates. I obviously don’t fully remember his response but it was probably along the line of ‘Then you just have to work harder’.

Anyway, I think I still have bad memory, to a large extent (And I know it isn’t getting better). This is probably why I like documenting things down. I’m not the best at it, but I try. Even the best among us, still have human memory. And it’s flawed. So documenting is a good habit for all!

Pretty much everywhere I worked, I found a way to document things in a way that can benefit others too. Have this got me into trouble?, maybe. But none of that would dissuade me from my documenting habit.

In one of those documentation efforts, hidden well behind corporate barbed wires, the first page says this.

“I am allergic to bad software. And I’m dying”

And boy do I see a lot of bad software. Bad software is not necessarily written by stupid or evil people. It’s usually done by people who are pushed by unrealistic deadlines. People who are shackled by an already bad body of software. Or people who do not know any better (not the same as stupid) or worse who do not care (so they don’t listen).

Before the enshittification era, I was comparing the new crop of nice, usable software interfaces with old DOS systems¹ I happened to see on Television. You know, those news stories giving us a glimpse of a life of a bank teller. I saw those and wondered if those people feel very bad using those systems after using nicer, free to use software interfaces in their personal lives.

I don’t know about those poor old bank tellers, but I can tell you, people know when they are using bad software and it can be truly painful, like Math can apparently be, to someone who don’t especially like it. However, people will eventually adapt to it and stop noticing it after a while but that does not mean that there is no better way.

This brings me to a story I still remember vividly to this day.

I was watching a computer operator running this script to setup some software, something likely irrelevant in the grand scheme of things. The program would ask for 3 different text values to be input. The computer they were working on was old and outdated, the workflow was extra tedious, even for this seemingly simple task. They grunted through this and sounded happy about the work done.

Before I move to the next part I must say, the first few runs of the program failed due to something else missing. Someone else with prior experience, who later turned out to be the author of the program in question was brought in and promptly advised to run a few commands, first to check some setting and then to set what’s missing. They ran these commands multiple times for reasons I do not understand but I gathered these commands are likely idempotent². I also noticed that the 3 inputs required were always the same for the lifetime of this task (which is a few months). What we’ve got in our hands is a rare good time to hardcode something!

When confronted that the 3 inputs can very well be hardcoded to make life easier for the operator and save time for all of us, I was lectured how this software will still be usable in 100 years (yes, that’s exactly the timeline they chose, though clearly exaggerated) and I knew I can’t argue against this visionary.

Next up was my misfortune of watching another operator having to repeat the task. This time on multiple computers. The first time they ran the software, they astutely figured out their fate.

“Oh my god, do I have to do this on all seven machines?”

Feeling validated about my assessment of the badness of this program, I chuckled and watched on. They had to repeat the few commands to set a missing setting, at which point I was wondering, “why are we not putting those in the script?” but I ain’t no visionary.

This was clearly a “minor” annoyance in software that may be used a few dozen times at best. However it shows how easily these paper cuts creep up on us and how easily they stay on, with misplaced dogma about a best practice in this specific case. One minor annoyance here, another there. Next thing we know, we are covered in paper cuts, bleeding to death.

This is why I believe that we should be a bit extremist about quality. Strive to do good work and leave any piece of software you work on in at least a slightly better shape than you found it. Now, I concede that it is not as easy as preaching. It takes real work, balancing good will and practicality and whatnot. But make quality your north star.

To tie things together with documentation, people who care try to “fix” in documentation what they are not allowed to fix in code. However, this noble deed can turn toxic when you move on from this, the software changes and some poor soul tries to find solace in your documentation. Now they are betrayed, twice for no fault of yours. Or theirs. I guess my point is that it’s best to try and not make bad software.

hé píng - 和平