The call usually comes before the handoff document does. Documenting a server you just inherited gives the next person a map while you learn what the machine actually runs.
Start Documenting a Server With Its Identity
Record instance name, host, environment, version, edition, service ownership, and business purpose. Include who to call for application and infrastructure questions. Without that context, a list of database names is a puzzle. Note whether the instance participates in high availability, replication, or a reporting pipeline. Document the expected maintenance window and escalation route.
When documenting a server, I start with facts the engine can show and questions a human must answer. Those two categories should remain separate. A server property query cannot tell you who approves downtime. The first page should let another DBA understand what service would be affected by a restart.
SELECT @@SERVERNAME AS instance_name,
SERVERPROPERTY(N'ComputerNamePhysicalNetBIOS') AS physical_host,
SERVERPROPERTY(N'ProductVersion') AS product_version,
SERVERPROPERTY(N'Edition') AS edition;Inventory Databases and Files
List every database, its state, recovery model, compatibility level, owner, and file locations. Mark which databases are application data, support data, or old migration leftovers. Do not delete an unfamiliar database during the documentation pass. A name can mislead, and a rarely used database can still have a scheduled dependency.
I add file sizes and growth settings because a useful map should warn the next DBA where capacity lives. A file path shows the Windows volume that needs monitoring. The query below provides the raw list. Add owner-confirmed purpose in the document beside it.
SELECT d.name AS database_name,
d.state_desc,
d.recovery_model_desc,
d.compatibility_level,
SUSER_SNAME(d.owner_sid) AS owner_name,
mf.type_desc,
mf.physical_name,
mf.size * 8.0 / 1024 AS allocated_mb
FROM sys.databases AS d
JOIN sys.master_files AS mf
ON mf.database_id = d.database_id
ORDER BY d.name, mf.file_id;Map Jobs to Business Work
Export job names, owners, schedules, and last outcomes. Then ask what each job accomplishes. A job called DailyTask tells the next person almost nothing. Record whether it performs backup, cleanup, import, report refresh, or application maintenance. Include external schedulers because not every process appears in SQL Agent.
I have seen a job marked disabled with no note and a team afraid to touch it. A single sentence explaining the reason would have saved a long meeting. Record disabled jobs and their expected future state. If the owner is unknown, flag that explicitly. Documentation should expose uncertainty instead of polishing it away.
Describe Recovery in Human Terms
List backup schedules, retention, storage destination, encryption dependencies, and the most recent verified restore test. Explain the order needed to restore critical databases. Include the target recovery time and acceptable data loss as agreed by the application owner. A screenshot of green job history does not prove a usable recovery path.
I put restore instructions near the front of the document. During an outage, nobody wants to search through twenty pages of server settings before finding the backup location. Include where to find the latest full, differential, and log backups, and who controls access. Keep secrets out of the document; link to the approved credential procedure instead.
Record Access and Ownership
Capture sysadmin membership, key server roles, service accounts, and application login owners. Note Windows groups and the team that controls their membership. List database owners and special permission arrangements. Do not paste passwords or tokens into a runbook. Documentation should point to the secure credential store and access request process.
I ask who can approve a new login and who reviews old ones. If the answer is unclear, record the gap as a task. A server can have technically correct permissions and still lack accountability. The next DBA needs to know which person can say whether access is justified. That is as useful as the GRANT statement itself.
Include Alerts and Known Problems
Document monitoring tools, alert destinations, error log review, storage thresholds, and known noisy warnings. Separate accepted exceptions from unresolved risks. A future on-call engineer should know whether a recurring message is understood or newly dangerous. Include recent incident references in the approved local system, without inventing stories in the server document.
I keep a short current-risks section. It changes more frequently than the identity section, so give it a review date. If an alert goes to a group mailbox, test that someone reads it. An alert that reaches only the archive folder is a fine filing system and a poor monitoring system.
Keep Scripts Beside the Narrative When Documenting a Server
Use read-only scripts to refresh the machine facts. Store their output with a capture date and keep the SQL itself nearby. Avoid hand-copying values into prose that will go stale. A script can gather version, databases, files, and jobs. It cannot decide application priority, retention, or whether a setting is an approved exception.
I separate generated snapshots from owner statements. That makes later reviews easier: refresh the query results, then ask which human decisions have changed. The goal is a document that can be maintained in minutes, not a giant binder that nobody dares update. A small accurate map beats a beautiful stale one.
Test the Handoff After Documenting a Server
Ask another DBA to find the backup path, job owner, alert route, and restart impact using only the document. If any answer requires a private chat, add it. Check that paths and names match the current server. Put the document in the team’s approved operations location and assign a review owner.
What would you need if this server paged you tonight? Write that first. Details can grow over time, but the recovery and contact facts should be ready now. Documenting a server is successful when the next person can take a safe first action without guessing at the server’s purpose. That is a practical test, not an editorial one.
Give Unknowns an Owner
An inherited-server document will contain unanswered questions. Put them in a visible section with a named person and due date. I distinguish unknown from not applicable because those labels lead to different actions. If backup retention is unknown, assign a check. If a job has no owner, list its name and ask the application team. Do not fill gaps with guesses to make the document look complete. A useful handoff tells the next DBA what is known, how each fact was verified, and which unanswered question matters most before the next maintenance window. That is more useful than a polished but fictional server map.
Related reading on this blog: How to Automatically Generate SQL Server Documentation ? and Document Your Databases with Data Dictionary and Diagrams.
A server inventory is not a handoff document, it is the raw material for an operational map.
Published by Pinal Dave on SQLAuthority. More of my work at pinaldave.com.
