Documentation matters more than the automation itself

The automation works. You built it six months ago. Now it breaks at 2 in the morning and you are on holiday.

Your colleague opens the script. Variables are named with abbreviations only you understand. There are no comments. Somewhere there are hardcoded values whose origin is unclear. The path to the credentials file points to your own machine.

This is the real cost of undocumented automation.

Why documentation gets skipped

Because the automation works. Once it is finished and tested, documentation does not feel urgent. And later never comes, because other things take priority.

The other reason is that the builder understands everything. The abbreviated variable names, the hardcoded values, the edge case logic. It is all obvious to the person who built it.

To no one else.

What good documentation actually means

Good documentation is not a manual. It means three things.

What this does, in words a colleague can understand without a technical background. Not "the script iterates AD group members", but "the script sends a weekly summary of the IT support ticket queue to the team email every Monday morning".

Why this was built the way it was. Edge cases that are not visible in the code. Why is there a 30-second delay? Why is a particular user group skipped? These decisions live in the builder's head, not in the code.

What to check if this breaks. Log locations, critical variables, external dependencies. Which service should be checked first? Which API key expires when?

A practical approach

Four lines of comments at the top of a script take one minute to write. They save a colleague three hours in a midnight incident.

# Name: Ticket queue summary
# Purpose: Sends a weekly summary of open tickets to the IT team
# Schedule: Mondays at 08:00, Task Scheduler / Server: srv-auto01
# Dependencies: ServiceDesk API (key: secrets/servicedesk-api.key), Teams webhook
# Contact: contact the automation owner if problems arise
# Last modified: 2026-05-14

Beyond that: keep the script in version control. Not "final_v3_REAL.ps1", but Git. History shows what changed and why.

Documentation is part of maintaining automation

Automation without documentation is a timed problem. Maybe it surfaces in six months, maybe in two years. But if no one else can maintain it, it is not automation. It is a single point of failure.

The best documentation is written at the same time as the code. Not after. Not later.

Want to review the documentation quality of your automations? Get in touch.