The oft repeated Continuous Delivery mantra is "if it hurts, do it more".
What about about things you don't want to do more? What about things you can't do more?
Sometimes you can simulate them or repeat on a smaller scale, but not always. Do you really want to practice moving if you only actually move once a year, if that?
There's no point on iterating to perfection on something which will change wildly between executions. It won't be unhelpful next time, but not enough to justify the time loss. You find 80% of the issues in the first attempt anyway.
An Example
I just setup a computer from scratch. This is the easiest non-trivial rare process I go through. I've invested much time and effort into backing up my data and making tools for reproducing my preferred setup with as few manual steps as possible. It still took multiple hours and I found a couple new bugs in scripts I use every day.
I'm not going to spend the next week ironing out every bug in the setup script because I need a functioning computer. Besides, I know I've fixed all the major bugs. Any issue which comes up next time will probably be a different unique combination of edge cases which I can't predict right now, because I don't have that computer.
This is the best case, a primarily automated process which minor dependencies on the outside world. Most physical things or anything involving other people are an order of magnitude harder to reproduce.
What to do?
Document
I've already mentioned the important point. You find most of the issues each time you actually do the thing. Iteration just encourages you to fix them in a consistent way. You can reap most of the benefits as long as you have the fixes ready for next time, and you actually implement them.
You'll run into new issues since the fixes won't be tested, but you should asymptotically approach the ideal perfect process eventually.
So how should you keep these fixes ready for next time?
Documentation.
But how?
I keep two kinds of documentation which should be stored together but are entirely distinct.
An Interlude
This step is mandatory. You are not allowed to skip it.
You must do it before writing things down, or you won't do it at all.
Setup some form of version control.
As a programmer, my platonic ideal for this is Git or other VCS. If you aren't a programmer and don't already know a VCS, use a word processor or equivalent which saves document history with timestamps. If you don't know or like tools which work like this, make duplicates each time you make major changes and put the date in the filename. If you prefer analog, write the date physically and take a photo.
Whatever works for you.
This needs to be as easy to edit and view history for as possible. Rare processes change between executions, but it's not always clear what will change and what is assumed by context. You're going to miss steps and assume things which are no longer true. Having the context of date and the exact version of the documents you were looking at, typos and all, will help your future self catch those mistakes.
Okay, back to the actual documentation.
Guided Instructions
This is the main living document. The gift to your future self who has forgotten everything about this process and just wants a simple checklist of steps to follow.
The instructions should be standalone, authoritative, and unambiguous. The end goal, the starting point, and how you get from one to the other. If you did the process from the start without mistakes, what would lead to the perfect outcome?
"Do X, then Y, then verify Z. If there's a problem with Z, the most likely causes are A or B, you can get further details at this link."
The first time you document the process, start by writing down your best guess for the steps. Then do the process and update the steps with more detail and any corrections as you go. Every subsequent time, follow the steps and change them as needed.
Keep in mind, this is for the happy path. You only want to give your future self the information they need to know to get things done. If there's a likely mistake or common snag, you can include that too. However, it should be written on the presumption that prior instructions were followed reasonably correctly.
If you make a stupid mistake and spend an hour fixing it, write what you should have done to avoid the mistake entirely. It's fine if you didn't actually do that, or if you're making a best guess at what you should have done. Leave a note that the step is a guess and move on. When I say note, you can literally just end the step with a question mark. It doesn't need to be detailed, just enough that you know it's likely to need updating next time.
The instructions are going to be an ideal for at least the first few iterations, especially for something with many moving parts which you do less than once a year. That's good, because it means you'll see where it's wrong next time and can make changes accordingly.
This imperfect means you still need a fallback for where the instructions go wrong though.
Reality Log
This is a secondary document, but it'll be much larger. It's also much simpler than the instructions.
If it happens, it goes in the log.
Anything at all. If you do a step, if you make a mistake, if you have an assumption or hypothesis about whats happening, what you should do, or what you should have done, write it down.
Even things which didn't happen. If you chose not to do something, write down why. If you realized you didn't need to do something that you did, write that down too. If you have to step away for an hour, write that down.
How could taking a break from doing the thing ever be relevant? Trust me, it is.
Knowing that you stepped away and may have forgotten things, or that things may have changed around you while you were elsewhere, is helpful.
Setting up a computer is the ideal case here. It shouldn't do much besides automatic upgrades and synchronization. What if you're in the middle of complicated paperwork and something you needed to input changed while you were out? You stop packing to move because you needed to change to go out, then realized you packed all your clothes.
The reality log is for the messiness of reality, and the messiness of reality is that steps are always an ideal. The instructions are never correct, and never will be. Write down why they're wrong here.
Save any resources you used as well.
Advice from a friend? Write it down. Website with information about doing a step that you already incorporated into the instructions? Save it anyway. You might want to see the context for doing that step again later, when you've forgotten.
Read a random forum post about your problem with zero useful information? Save the link and label that it was useless. It will prevent your future self from reading it again because you've forgotten it was useless.
I'm dead serious.
I've done this before, multiple times.
I've read the same useless forum post three times across four years.
If it happens, write it down
Don't try to adapt or smooth out the log in the slightest. That's the point of the instructions. You put all the cleaned up, everything goes perfectly instructions in there so your future self never needs to read this garbage again. And then when they inevitably do anyway because you made a mistake on what needed to be in the instructions, you still have the complete record.
Even if you make a stupid mistake which would never happen again, it goes in.
"I spent three hours chasing down a weird error because the cat walked on my keyboard and changed the configuration while I was in the bathroom." Good. It needs to be perfectly honest about what happened, because if you skip something on the basis that "it doesn't matter", you'll eventually miss the one time where it did matter and you didn't realize why at the time.
Letting Go
Documenting is slow. Even for a rare process, the more you do it the easier it becomes. The tradeoff for how much documentation is worth doing shifts.
If you do a rare process enough times and find yourself barely updating the instructions, you can reduce the amount you write. I wouldn't abandon the reality log entirely, but you can only write down where you deviated from the instructions and any major issues. You build your sense for what doesn't matter in a task as you do it, and as that confidence builds you can lean less on excessive documentation.
I used to have detailed instructions and checklists for preparing for a trip. Logs used to be a massive checklist of what I actually packed, what admin I took care of, and then a slightly shorter list of what I used, written while unpacking.
Last trip, I didn't even bother with the packing list and my unpacking log was barely a sentence. "bring extra pencil, good jacket combo, controller?" Expanded out so you can understand it, it was roughly "extra pencil was surprisingly useful, made the right choice about which jacket to wear, I had more free time than I anticipated so maybe I should have packed a controller".
These are all specific, minor choices made for that trip. I probably will bring an extra pencil on the next trip, but I might need a different jacket. Nothing major changed, so I don't need the instructions anymore. Just the specific choices so I can continue honing my judgment for those edge case minor packing choices next time. That's the only useful thing at this point.
I also used to have a lot of trouble setting up networking on my computer. I had detailed logs of everything I attempted and all the mistakes I made. These days I have the instructions so perfectly nailed down that I don't touch the log and just skim over the instructions to check my memory before hitting all the buttons.
In general, the more variable something is, the more likely the reality log is to be useful. The more detailed something is, the more likely the instructions are to be useful. You can cut back on either or both as you do a process more and trust more in your documentation.
It's the fallback of having both which lets you cut back on either.
- Rew
Nightly Notes
One way of interpreting this blog is as rough guided instructions to life, with some extra prose and justifications.
The Nightly Notes are not the reality log. Trust me, you don't want to see the actual reality log. My reality log for living life is an archive of text files with just enough labeling and spellcheck that I can probably search for something if I need it again someday.
Anyway.
Writing.
Another multiday draft I'm happy with. This is the longest post yet. One more hour of editing would be nice, but I have things to do.
It'll go out as it is.
Progress is progress.
I also realized this blog is probably confusing to anyone who stumbles across it, so I added a link to the first post which had all the "who am I what is this" at the end. I hope that helps someone?
While looking at that, I realized I mostly stopped using footnotes. Couple reasons for that.
- I was more nervous about writing and tried to catch what I thought might be an issue in footnotes.
- I do less editing now than I did then, so I don't have time to think of all the extra caveats and references that would go into footnotes.
- I'm still trying to figure out my relationship with referencing specific outside sources.
- I'm trying to incorporate those loose footnote type thoughts into the main post because I'm realizing they deserve more attention
I'm not committing to abandoning them entirely, but it's a change I don't see reason to fight.
- Rew