This is not new information and this is not a new idea that you’re about to read. This isn’t a novel idea. This isn’t something that no one has ever discussed. This is the furthest thing from a new idea.

Instead, this is me re-iterating something that people in our field talk about over and over and over. It bears repeating though because it still comes up again. And with good reason: It’s a good reminder that we should be doing this.

We should be keeping a journal of the work we do. Really.

UpNote is a good app for this.

I don’t mean a blog, as much as I think they’re important, and I don’t mean Twitter threads, I don’t mean comments on Hacker News, and I don’t mean Stack Overflow questions or answers.

I mean text files or markdown files or HTML files or whatever it is you want to use. Here’s why: The longer you work in software, specifically on the web, the more likely you’re going to encounter all sorts of other software required just to get The Thing™️ working. And the less likely your exact situation is identical to someone else’s.

Sure they – or you – can say “Have you tried [doing this]?” or they can recommend “Upgrade [this particular package]?” or “Bypass [this particular dependency] because it’s likely not needed.”

That still leaves a lot of unknowns. They are suggestions.

Keep a Journal

Case in point: This week, I needed to get something stood up on my local machine. Aside from your usual stack of software required to run the web application, I needed:

  • Node, but not just any version of the software.
  • NPM, but not just any version of NPM.
  • Gulp, but not just any version of Gulp.

Though I got it working, it’s completely beside the point. The point is that had I not been faced with a similar situation several times in my career I wouldn’t have recognized that I needed to start taking notes as soon as things started to go sideways.

So maybe this is the cautionary tale that can help you shortcut your mistake.

My Cautionary Tale (Don’t Make The Same Mistake!)

Anyway, at this point in my career, I’ve been doing this long enough to know how this plays out so the moment things started to break in my terminal before I even got the software running I opened my Markdown editor and started the the process.

This is how it pans out:

  1. Define what it is I need to do.
  2. Walk through the steps that I do.
  3. When it fails, paste the error and try to explain it. Link to references online, if necessary and/or possible.
  4. Repeat starting at Step 2 until I can break out of the loop.

Assuming I need to add a new feature to an existing application, assume the first step of what I need to get is get the application running my local machine.

How This Recently Played Out

This is what the journal looks like:

  1. I need to upgrade The Application but before doing that I need to make sure several dependencies are built.
  2. Run the dependency manager in the terminal to build the assets.
  3. If the build process succeeds, I’m done. If the build process fails, then I go to the next step.
  4. Read through the terminal output and the error log to understand the problem. Search the web, if necessary, and capture the information.
  5. Downgrade the build tool and document the version of the build tool and the version now being used to build the assets.
  6. Repeat Step 2. If it works, great – I’ll move forward; if not, start over.

It’s tedious, yes, but in the future when something like this inevitably happens again, or you have a teammate that experiences something similar, or someone you know in another company is asking something about something like this then you’ve got the knowledge captured.

You don’t have to say Oh yeah, I remember experiencing this. I wish I’d written this down.

Because you did.

A Side Note on Cautionary Tales

First, a taboo or prohibition is stated: some act, location, or thing is said to be dangerous. Then, the narrative itself is told: someone disregarded the warning and performed the forbidden act. Finally, the violator comes to an unpleasant fate, which is frequently related in expansive and grisly detail.

Cautionary Tale via Wikipedia

What’s this look like in our case?

  1. The Dangerous Act: Trying to stand up the application without any guidance.
  2. The Dangerous Act Performed: Standing up the application without any guidance, discussion with peers, or reading a README or previous journal entry is done.
  3. The Fate: The application doesn’t work and you’re left trying to figure out exactly how to approach the problem.

So when I say these are cautionary tales, it’s not hyperbole 🙂. Mostly.