I manage a small, mostly cloud-based environment and want to leave a useful handoff for whoever takes over. There isn't much documentation yet, though I have a log of tasks and changes. What should I cover, and how should I organize it?
How should I document an IT environment for the next administrator?
Answers
Start with a map of the environment, not a giant diary. List the services, what each one does, how they connect, and where to find their administration interfaces. Include the network basics such as DNS, DHCP, domains, and any on-site equipment.
Then add short walkthroughs for common tasks and user issues. Your task log can help jog your memory, but turn the useful bits into current instructions rather than making the next person read through years of entries.
Reply to this answer
Write down the weird stuff first. If one service needs another restarted, or a setting looks wrong but solves a particular problem, explain both what to do and why it's that way. Those are the details someone can't easily reconstruct from a vendor's documentation.
Assume the reader knows IT but doesn't know your environment. A few extra sentences of context can save a lot of troubleshooting.
Reply to this answer
Make access its own handoff task. Keep credentials in a password manager, and document how an authorized successor gets access, including any unusual login methods. The business needs to know where the access information is and how to retrieve it safely.
Also think about what happens if the system you're documenting is unavailable. Documentation or recovery information locked inside that same system won't help much during an outage. A securely stored hard copy is one option for essential recovery details.
Reply to this answer
Use a tool the company already knows and can maintain, whether that's a shared notebook or a knowledge base. Search and straightforward access matter more than picking the fanciest platform. Keep the daily activity log separate from the pages that describe how things currently work.
Reply to this answer
Don't try to capture everything in one pass. Ask what would cause the biggest problem tomorrow if nobody knew how to fix it, and start there. Add a little documentation as you work through normal tasks, then check each service you manage for gaps before the handoff.
Reply to this answer
Add your answer
Answers are reviewed before publication.
!set+aside~the_mittens:
Use terms people will actually search for. A page about a server should mention DNS if that's one of the things it handles.