Here’s the problem we need to address: many of the things IT teams do aren’t documented because they’re seen as busy work, there’s no time, people forget, or they just don’t want to. But here’s the thing: documentation may take some time, but it takes exponentially more time to research a solution every time you need it.
For example, it might take 20–30 minutes to create a quality document. Researching a solution can take 10–15 minutes, and if you need to research it 2–3 times, that’s 20–45 minutes of research. Meanwhile, it only takes about 5 minutes to re-read a well-written document. So, let’s get started on how to do this.
It happens all the time: you figure out a solution or process, implement it, and move on to the next task on your never-shrinking to-do list. A few months later, you need to do the same thing again and must dig through scripts, tickets, blogs, Slack, or wherever you found the solution, trying to recreate it. It takes a lot of time, and you think, “I really should have documented that.” Then past you silently curses present you for not documenting.
Here’s how to create quality documentation so future you doesn’t curse past you. First, it’s important to note: documentation should be a living process that is revisited regularly. Processes change, environments get new apps, and Apple releases new security measures, looking at you, Managed Login Items!
Beyond just remembering how you did things, documentation serves many purposes. Especially as organizations scale,one-person operations expand, help/service desks are created, MSPs are hired, directors join, or systems get more complex, quality documentation reduces escalations, speeds up knowledge transfer, and gives you a method to analyze what you’re doing and why.
When you write documentation, take it step by step. Your first step isn’t writing, it's recognizing that documentation is not busy work. It’s actually the first thing I start at any new job.
Let’s use Mac setups as an example. Grab a computer off the shelf and set up a Mac for a new employee. If possible, do this twice: once using Automated Device Enrollment and once with User-Initiated Enrollment. Even better, record it using QuickTime or another screen recording tool. This allows you to re-watch it, catch all the idiosyncrasies, and see where it can be improved.
Once enrollment is finished, go through the Jamf policy logs and note the order of operations, including profiles, apps, policies, etc. Document the entire process, every step you take. If you have a screen recording, try to grab screenshots to include in the document.
Next, figure out who your documentation is for. Is it for users, help desk staff, yourself, management, or someone else? Cater the language to your audience. Decide on a structure and use that structure consistently across documents because this makes writing easier in the future.
After writing the document, re-read it and ask: Does this document answer the question I’m trying to answer? If yes, great edit and finalize it. If no, revise it until it does. This may require rewriting, and that’s part of the process.
Once you have a solid draft, ask a trusted colleague to test it. Have them follow it step by step to see if anything is confusing. This step is crucial because we all work differently. What makes sense in your head may not make sense to someone else. Take their edits, adjust the document, and have them test it again. Repeat this process with multiple colleagues until it makes sense for as many people as possible. Note: you’ll never get it perfect for everyone in every scenario.
Finally, store the document in a consistent, organized location, and make sure all teams know how to find it. What about revisions? My cadence is yearly, during testing of each new macOS version. Your cadence may differ depending on the document.
