Internal Engineering Documentation

How engineering operates, published openly so a team can point to a doc instead of waiting for you. The “MDDS point of view” exists, is citable, and matches production reality — or it doesn’t ship.

What it is

This is the documentation pilot named in the intro: more of how engineering operates, published openly on maryland.dev, so agency engineers and deployed-team members have reusable guidance to point to.

The artifact is canonical guidance — the operating model, runbooks, and most of all the MDDS point of view on the decisions agencies keep getting wrong. The clearest example is the “Salesforce will fix everything” wall from the intro: right now every engineer argues build-vs-buy-vs-existing-tool from scratch, against agency leadership that’s usually already decided. A published, citable MDDS position turns that lonely argument into a reference you point to.

Like question sets, this is an inheritance artifact. A doc you write once stops you — and the next engineer — from re-explaining the same thing for the rest of your tenure.

How you run it

Decide what’s worth canonizing. Not everything should be a doc; the canon is the small set of things teams keep needing and keep getting wrong. The build-vs-buy point of view, the operating model, the runbook for the thing that breaks the same way at every agency — those earn a page. Most things don’t.

Keep docs truthful and current — this is the whole job. Every doc carries a last_verified date and a review cadence, because a doc that’s drifted from production is worse than no doc: it’s wrong with authority. Model the writing standard yourself, because the docs are also how you teach what good engineering writing looks like.

Make docs the default reference. Publish openly on maryland.dev so anyone can point to a URL — https://maryland.dev is a link a team can paste into an email, not a thing they have to be in the room to hear. The commitment you’re making is that the doc is the answer, so engineers stop re-explaining the same thing live and start sending the link.

How you show up

Write or commission the canonical point-of-view docs. The MDDS position on build vs. buy doesn’t exist until someone writes it down — and you’re the someone, or you find and edit the someone. Either way you own that the position is coherent and defensible, because it’s about to be cited in rooms you’re not in.

Review for truthfulness. Your highest-value act here is not writing — it’s checking that what’s published matches what’s actually running. A doc that describes the pipeline the team meant to build, not the one in production, is the failure mode that makes documentation untrustworthy. Read every doc against reality before it ships, and again on its review cadence.

Templates

The hard part of a doc isn’t the prose — it’s making it findable, owned, and obviously current, so a team trusts it instead of asking you. These are the copy-paste starters for that. Swap anything in [brackets] for your specifics, and replace [owner], [date], and [url] with the real ones. The structure is doing the work: a freshness header and a named owner are what keep a published doc from quietly rotting into the wrong-with-authority failure mode.

Doc page skeleton

The standard shape for a published page. Lead with the freshness header, say what it is and when to use it, give numbered steps, and close with the line that tells a reader how to flag it when it’s wrong.

Last verified: [date] · Owner: [name]

# [Doc title — the question it answers, not a topic]

What it is
[One or two sentences. The MDDS position, the runbook, the operating
model — what a reader gets by reading this.]

When to use it
[The situation that should send someone here. "When an agency says
Salesforce will fix it." "When the thing breaks the same way again."]

Steps
1. [First action.]
2. [Next action.]
3. [Last action — what "done" looks like.]

If this is wrong or out of date, tell [owner] — a stale doc is worse
than no doc, and you flagging it is how we keep it true.

Notice the doc names the question it answers, not just a topic — that’s findability: a team reaching for an answer recognizes the page, instead of asking you something a doc already covers.

Freshness header

The small block that sits at the top of every doc. It’s the whole defense against drift — the date and the owner are what you check on the review cadence.

Last verified: [date] · Owner: [name]

Notice the date and owner travel together. Write-once, never-update starts the moment a doc has no owner to re-verify it — the header is what makes the “docs drift from reality” failure visible instead of silent.

Announce a doc

A short message that points someone to the doc instead of answering live. Send it when the question lands in office hours, intake, or a thread.

Good question — and instead of waiting on us, here's the doc: [url]

It's the MDDS point of view on [topic], and it's current as of
[date]. If it doesn't answer what you're stuck on, reply here and
I'll fill the gap.

Notice you send the link, not the answer. The commitment this pilot makes is that the doc is the answer — every time you re-explain it live instead, you teach the team the link doesn’t really work.

Stale-doc review ping

A message to the owner when “last verified” is old. It asks them to re-verify against production or hand the doc off — the cadence only works if someone acts on it.

Hi [owner],

[Doc title] is due for review — last verified [date], and the system
it describes has moved since. Can you check it against what's actually
running and bump the date, or hand it off if it's not yours anymore?

A doc that's drifted is worse than absent, because teams trust it. Ten
minutes now keeps it from being confidently wrong.

Notice this is aimed at the “single commit” doc. Treating publishing as the start, not the finish, is exactly this ping — the cadence enforced as a real message to a real owner, not a date that quietly ages.

What good looks like

An agency engineer points to a doc instead of waiting for you to be available.
“The MDDS point of view” exists, is written down, and is citable in a vendor or leadership meeting.
Docs carry a last_verified date that’s actually recent — and the date is true.
The same explanation stops being given live, because the link does the work.
A new deployed-team member reads the canon and walks in further forward.

Where it goes wrong

Docs drift from reality

The doc was true when written and isn’t anymore — the system changed and the page didn’t. Now it’s confidently wrong, which is worse than absent, because a team trusts it. The tell: a last_verified date older than the last real change to the system it describes. The fix is the review cadence, enforced — a doc nobody re-verifies is a doc decaying, and the date is how you catch it.

Write-once, never-update

A doc gets written in a burst of energy and never touched again. The canon ages into a museum of how engineering used to operate. The tell: every doc’s history is a single commit. Treat publishing as the start, not the finish — a doc without an owner and a cadence is a doc you’re already losing.

Performative modernization

The docs look thorough and behavior doesn’t change. The org “has documentation,” cites it in a status report, and nobody’s daily practice moved — and the existence of the doc reduces the pressure to actually change anything. The tell: the doc is published and current, but the thing it documents still happens the old way in the room. A doc is only real when teams act on it; published-and-ignored is theater.

Docs nobody can find

The guidance exists and is buried — wrong place, no link, not where anyone looks. Findability is half the product; an uncitable doc may as well be unwritten. The tell: people ask you a question that a doc already answers, because they couldn’t find the doc. Put it where the question gets asked, and link to it from office hours and intake until the link is reflexive.

What it tells us

What gets asked repeatedly is what should become a doc. The backlog of what to canonize isn’t a guess — it’s fed directly by office hours themes and intake patterns. The third time the same question crosses your desk, you’re not answering it again; you’re writing the doc.

So read the documentation backlog as a signal, not a chore. It feeds the four questions — a question that unblocks more than one team is a doc, and a category you can’t doc your way out of because it genuinely needs an expert is a hiring signal. The canon and its gaps together map where the deployed teams’ shared knowledge is thin.