When You Don’t Know, Document

I’m going to share a shameful secret today.

I’m afraid of servers. Terrified.

Everything about them frightens me: Setting them up, configuring them, keeping them running. When I talk to a support rep at a hosting company, I curl into the fetal position and use expressions to mask my ignorance.

“Now, I should know this but…”

“Just to be sure I understand…”

Sysadmins and Devops gurus are superhuman to me.

Dealing with the unknown is frightening, especially when working with clients. To clients, all technical stuff is the same, and you’re expected to know it all.

As a young, naive developer, I dealt with the uncertainty by being a sysadmin cowboy. I’d Google a tutorial, SSH in, bang out some shell commands until the server…oh wait, that didn’t work.

OK, how do I uninstall what I just installed? Forget it.

Back to Google. New tutorial. New shell commands. Didn’t work.

Back to Google. You get the picture.

Eventually, I had a working server, but I had no idea how it got there. If the server had issues, it was back to the drawing board – except there were no drawings to reference.

I desperately wanted servers to be “not my problem”.

A different approach

I’ve matured. I still fear servers, but I approach problems I don’t understand differently: I learn from them. I take notes.

I mean heaps of notes

The next time you’re facing a problem you have no experience with, open up your text editor (or note-taking app) and create a new file: documentation.txt.

Document everything. Every single thought process. Every shell command. Every database change. Here’s some notes I took from a recent server setup:

I take notes on my thoughts, not just the commands I ran. When I reference this later, I won’t be wondering why I did this – it’s all there in the documentation.

Move slowly & keep it updated

Anxiety will make you want to run ahead. Don’t. Pace yourself. Keep your documentation updated. If you make a change to a step, go back and update it. Leave nothing to “figure out” later.

When you see the finish line, don’t start sprinting. Inevitably, I think “of course I’ll know what to do at this point”. Maybe I would – but the dev who picks up the project after me would sure appreciate an explanation.

When to use this approach

I recommend taking detailed notes for “stateful” problems – things that need to be undone in an orderly manner. Some examples: database changes, server setup, modifying existing codebases.

When not to use this approach

I don’t recommend this approach for experimenting with a new tool: Specifically, new libraries. If you’ve never used D3.js, it’s not worth documenting out your initial experiments. For these, I recommend hacking away until you have a better understanding, then throwing out your hacks. That’s a subject for another article.

Keep learning

An important side effect of intense & excessive documentation is that your learning will stick.

Prior to becoming a freelancer, I had set up and managed several servers. And yet, when I needed to set up a server for a client, I had the same anxiety I always had.

But this time, it was different. I documented. I learned. I’m a little less afraid.

Freelancer? Me too!

I made lots of mistakes growing my business. Maybe I can help you avoid those mistakes?

Join my newsletter and I'll send you my best content about the business of freelancing and software, for free.

Powered by ConvertKit

Leave a Reply

Close Menu