Hey everyone,
I'm getting pretty fed up with how much I have to document everything manually. I typically use Terraform and Ansible for my setup, but I don't automate every single action because sometimes it's just quicker to do it by hand rather than spend hours creating a script that does it automatically. My company has been asking me to develop internal guides for these actions so we can refer back to them later.
Currently, I often use AI to help me and just copy and paste what I've done, then tidy it up. So I'm wondering, is this a common struggle for you guys? Do you create guides regularly, and what types of tasks do you document? Also, are there any tools that could help streamline this process?
1 Answer
We refer to our documentation as runbooks. It's essential for them to be accessible and written clearly for the engineering team, not just management. Each runbook should clearly outline the problem being addressed and include simple, copy-paste commands. We maintain these in a git repository so everyone can refer back to them easily and keep everything up to date. Automation is prioritized for frequently used runbooks, which makes life easier during late-night incidents. Runbooks are a necessary evil—without them, teamwork and training for newer members take a hit.
You bring up a good point! We’ve tried several formats for runbooks, but often we find that creating them takes longer than just automating the tasks in the first place. Do you use any AI or capture tools for documentation, or is it all handwritten in Markdown?