I recently made a post on Reddit that I didn’t expect to get much of a response from. I was just feeling good about something that happened at work. I was shocked at how much it took off. What really surpised me was how many people asked, in the comments and in private messages, how I write good documentation. There were also a lot of folks asking if I have a website where I talk about work and such from the perspective of someone with ADHD. It was the kick in the ass that I needed to resurrect this space.
The reality is that my skills at writing documentation are born of necessity and come from a place of sheer terror. I will freely admit that what I’m terrified of has never happened but that doesn’t stop me from feeling a deep fear that someone will use my documentation, get something wrong, and I’ll end up with the blame. I hate writing documentaiton. Regardless of how good my documentation is or how much praise I receive writing it is an exercise that most folks with ADHD will completely understand. I agonize over every phrase, I tend to write three paragprahs where one will suffice, and I have to edit myself constantly. I am good at writing documentation but it is, by no means, something that comes easily to me.
I have not always been good at it though. When I started my career I sucked at it. While I could capture the actual keystrokes necessary for a copy-and-paste recipe the reality is that my documentation was all over the place. I couldn’t even follow it later so I had to do something about it. If nothing else I needed to be able to repeat what I’d just done and I was barely capable of that. So I developed a system for taking notes that allowed me to repeat tasks without having to remember all the little details. That system is still the basis for how I write documenation. It has evolved over the years but at the root it is simply this:
- Copy the command just issued or document what I clicked, along with any output into a text editor
- Write one single sentence describing what was accomplished by the doing the thing
- If necessary write a second sentence for clarity
- If a screenshot was used prepend or append the filename to the end of this entry
I currently use Joplin for taking notes and this is what a series of commands looks like:
There are some additions here, like indented bits about what fields need to be edited at each step, but the overall note-taking follows what I stated above. It does change in minor ways depending on whether I’m working with a command line, a GUI, or BIOS but the base is always the same. The key is that I pretty much do this for everything I am working on. I don’t edit during this, at all. I copy full command output even it is multiple screens long, I screenshot everything. At this point I do this without thinking as it’s just part of my work routine. While this creates the base for my documentation the reality is that looks absolutely insane to just about anyone else. I have never actually talked to anyone else with ADHD about how I do this so it might make perfect sense to those with brains like mine.
When I have to convert these notes into actual documentation is when things get rough. As you can see, just by reading this, I am verbose. This is something everyone with ADHD will likely recognize. A large majority of us live with the fear of being misunderstood. We have spent our lives being accused of being lazy, stupid, and other things that aren’t true. We know these things aren’t true and as such have developed defense mechanisms, like being verbose, in order to preserve our mental health. I’ll get more into that in another post but hopefully that’s enough of an explanation to give the neurotypical reader some context.
Writing the actual documentation is a simple process. Take the notes, keep the stuff that’s necessary, and put it into whatever system your job requires you to use for documentation. Simple doesn’t mean easy for those with ADHD so I have a system that makes it seem sane for me. My current position requires me to use Confluence for documentation but this has also worked for Word, Libre Office, MediaWiki, and more. I start by inserting a Table of Contents as I’ll forget if I don’t do this first. I then write an overview that tells what the documentation covers, what it doeswhyn’t, and any assumptions I’ve made. For the documentation I’m using a reference, produced from the notes in the screenshot above, this is was the Overview:
The level of detail in the overview will all depend on the audience you are targeting. The more separation of the technical skills between me and the audience the harder the Overview is to write. I am really lucky that, right now, I can assume that my audience is on par with technically even if they aren’t familiar with the system for which I am writing documentation.
Once the Overview is complete the conversion of my notes to documentation begins and this what always leaves me useless after I’m done. The amount of mental effort and self editing required pretty much turns me into a quivering, emotional blob for the rest of the day. This process requires some understanding of how to edit yourself for your audience. I don’t know how to explain how to do that. It’s something that I’ve learned to do over my 30+ plus career. The more technical my audience is the less detail I need to add to the directions. With the documentation that I’m using as an example it’s pretty much a step by step guide to an install that is more concise than the vendor’s documentation and written specifically for our environment. I didn’t crib from the vendor’s documentation as I used it while producing my initial notes but I do crib from vendor’s docs at times and there’s nothing wrong with doing that.
The actual documentation that was produced using the notes in the earlier screenshot looks like this:
That’s a snippet but it shows how I use screenshots and have edited them to highlight the fields that are supposed to be changed. I prefer using inline code blocks instead of double quotes as I used in the text but that’s how my company does things so that’s how I do it at the moment.
For installations documentation is pretty straightforward. It’s almost always step by step and so you don’t have to make any decisions about what order to put things in. However when you get start getting in to things like managing users and access via something like FreeIPA then it gets a little trickier as you have to make more editorial decisions. My general rule of thumb is to break things into separate pages by role and under those pages document the most common tasks first so they are easy to find.
Design documents are probably the hardest thing I currently tackle. Not all of the notes will be taken by me as it’s frequently a situation where I have been told to implement X with Y configuration. This still requires a design document but just covering the what without addressing the why leaves a lot to be desired. In this case I end up asking a lot of questions so I understand why things are being done in the manner I’ve been told to do them. This type of document is where I really have to self edit. I could easily spend three or four paragraphs talking about why we’ve implemented any feature of any application the way we have. However most of that would irrelevant to anyone using, managing, or implementing the system. The key to a good design document, in the context of my current environment, it getting enough information onto the page without making anyone’s eyes glaze over. I don’t always accomplish that but the reality is that most folks I’ve worked with skimp on these documents so my occasional foray into verbosity is overlooked. The reality is that too much information is always better than not enough. Neurotypical people weed out the bits that might could have been cut but if you leave room for assumptions that creates some pretty ugly situations.
In the end all documentation is a special for me. I am proud of the end product because it’s something I’ve driven myself to be good at over a 30 year career. What that looks like is me attempting to make use of the general terror it brings and deadlines to increase my stress levels to where I can work without getting distracted by whatever YouTube is suggesting I watch, or the neat project I am starting after to documentation is done that I really want to start now because documentation is boring, or any of the myriad things that my brain will throw at me.
As far as what makes for good documentation? I don’t honestly know. I can’t quantify that for you. I have been told that mine is good because I strike a balance between something you could cut and paste and having way too much information. So from my perspective it appears that good documentation grows from knowing how to self edit. It has to have enough detail that your audience can follow enough but be edited enough that you don’t lose them.
Looking back over this I think that the second most important is knowing your audience. There are vast differences, for instance, between technical documentation of any sort and end user documentation. That seems be something I’ve always been able to do. I don’t know if it’s something I learned as a coping mechanism or something that’s innate but being able to gauge my audience has helped me with more than any single other thing when it comes to documentation. Yes my note taking skills are the bedrock but that’s where the actual content comes from. Long before I ever insert a Table of Contents I have thought about the audience and know how I’m going to write the overall document.
I would say that, for me, it boils down to note taking and knowing your audience. That’s the external side though, the internal side or the ADHD side is knowing how to channel the chaos/fear/stress recipe into something that keeps you typing. What works for me doesn’t work for everyone. I can’t write documentation with headphones on but I’ve seen people swear by it. You really have to learn what works for you and be honest with yourself about what doesn’t. Having ADHD doesn’t mean that writing good documentation is out of your reach. It’s just like every other thing in our lives, the way we get there and get it done will make no sense to neurotypical folks and will sound batshit crazy when we talk about it.
This is a skill I’ve developed out of necessity. That doesn’t make it easy nor does it make it enjoyable. I didn’t manage to write a single good essay at any point during school and, believe me, documentation is really similar. Your journey may be different than mine but if reading about mine helps you then I am happy to scream these words into the void!
