Don't Wait to Document - Part 2
In the previous post I talked about the benefits of not waiting to document in code. With that out of the way I can zoom out a bit and discuss documentation more generally.
The idea behind this blog is the same idea behind this post: waiting to write something down almost never works. What I write now isn't going to be perfect or complete. It's still worth writing! That's a lesson that I keep relearning over and over in different parts of my life. How about some examples?
Work
- Product documentation: There's only so much product knowledge you can accumulate before it's "one thing in, one thing out". If this knowledge isn't written down, write it! Even though it may change or not be 100% correct, that's at least better than 0%.
- Communication: I've never had a miscommunication that was due to writing down too much.
- Employee evaluation - team: Team members do great things between 1-on-1 meetings yet somehow those meetings tend to focus on whatever is most recent.
- Employee evaluation - personal: I accomplish a lot between yearly personal evaluation time and yet somehow that meeting tends to focus on the last couple of months.
- Code: see Part 1.
- Meetings: It's important to know what was discussed during a meeting so that you only have to discuss it once.
Technology At Home
- Computers: They accumulate and rarely leave. For each computer you own, do you know everything hosted on them, what's on their storage, credentials, etc? I keep server credentials in a password manager. In the server's home directory I keep notes about what services are on the computer, maintenance instructions if needed, and scripts for common tasks.
- Network: If your network devices don't maintain a map for you, make one. Knowing what device is plugged into which switch is incredibly helpful when you have more than one. Related: I run an instance of Dashy on my network so I don't need to assign or remember local host names. I assign a static IP to the host and then put that in Dashy with the name of the service. Bam! All I have to remember is the host that Dashy runs on.
- Wiring: Label, label, label. You'll thank yourself later. The next person who lives in your home will thank you.
Life
- Calendar: Not just a date, time, and location. Notes remind me of what I'm supposed to do when I get there, where my tickets are, etc.
- Lists: To do lists, groceries, projects, wishlists. Add to them as you think of things!
- Blogging: Wait a second how did this get here...
There are so many more examples. The common thread here is that writing down a little bit of information in the right place can save you a lot of time in the future. Imagine writing your to do list only once a week - it's going to take longer and if you're a human being you're almost guaranteed to miss things.
I decided to try to add blogging to my documentation tool belt. My two main goals are to first to commit to practice writing, and second to write down some thoughts for referencing them later.
The first goal, practicing writing, is to help grow a skill in a low-pressure way. I doubt anyone is going to read this, but writing as if someone will one day helps make this effortful practice that will help me in the future.
The second goal is to write down thoughts for referencing later. This is really two goals in one. Writing down thoughts, especially "publicly", forces me to think through topics in a deeper way. I couldn't have imagined that I had more than 1000 (edited!) words to say about documentation. After these first few ideas I'll also have to put some real thought into what topics I want to write posts about. The second half of this goal is to have a place where my thoughts are written down. I can come back in a year to see how my perspective has changed or send a link to someone so I don't have to repeat a thought :)
The point of this whole post is to say: write things down and don't wait to do it! Small investments over a long period of time can add up to something powerful.