Our engineering team produces documents that matter beyond the team: reviews of our applications, records of design decisions, standards, and lessons learned. Before this platform, those documents lived inside each project’s code repository, which is where a colleague outside the team would never look. A finding nobody can read might as well not exist. This platform is the team’s own internal website for those documents. Publishing one gives it a web address a colleague can open, and every version ever published is kept, along with who published it and when.
We chose not to buy or install a wiki or a documentation product. Any system like that is one more thing to run, back up, and secure. Instead, the documents stay in the same version-controlled storage the team already trusts for its code, and the website is generated from them. Nothing can be edited behind the record’s back, and if the website were ever lost, it is rebuilt from the source in minutes. The trade is that there is no editing in the browser; every change goes through a publish step, and we consider that a feature, because the publish step is the audit trail.
The platform’s first serious bug wiped out data, and the honest account of it is published on the platform itself. Early on, publishing a new version of a document silently overwrote the stored source of the previous version, and one project’s earliest sources are gone for good. The fix keeps every version’s source separately, and the loss is recorded plainly instead of tidied away.
At the latest count, 7 projects publish here, more than 30 documents in all, including the two large application reviews described on the Residential Client Portal and Job Scheduler pages. Publishing is a single request during a working session, handled by a shared tool, so putting a document on the platform never depends on someone remembering a procedure.
The same principle runs through the team’s whole record of its work: as work moves, the record updates itself. Requests arrive in Freshservice and move onto the team’s monday.com board, by hand today, with a scheduled job planned to take that step over. Management weighs in on the board, and nothing gets worked without its approval. From there, the shared tools flip an item’s status and write the running log as work starts, reaches testing, and goes live, with nobody typing an update from memory at the end of the week. Progress notes are the kind of work people tend to skip, so here the mechanism does them. A full check found all 46 pages and 567 internal links working, the whole site weighed under 15 megabytes, and it was built in under three weeks. It now runs on the same server as our production applications.
The technical detail
This is the engineering group’s documentation platform, live on the company intranet behind domain sign-in: a roughly 1,100-line PowerShell publishing script and a server setup script that render Markdown into a static HTML site on IIS. Content is organized as project, then document, then revision, and each revision keeps three things: the rendered page, the Markdown source it came from, and a history file recording who published it, when, and from which machine. The governing rule is that the git repository is the system of record and the website is a rendering of it, never the other way around. Mermaid diagrams render from a vendored copy of the library instead of a public CDN, because the intranet cannot assume outside connectivity.
The design, and the alternative not built
The obvious build was a wiki or a database-backed documentation product. We did not build one, for a reason that generalizes: every stateful system a small team adds is another thing to run, back up, patch, and secure, and documentation is the least forgiving place to discover that a backup was not happening. A static rendering of version-controlled files costs almost nothing to host, cannot be edited around its history, and restores from the repository by definition.
The cost of that choice is no live editing, no comments, and a publish step for every change. For engineering documentation, where the source already lives in repositories and changes already move through review, the publish step is not friction. It is the audit trail.
Built by the machinery, not by hand
Most of what the platform carries is not written by hand, and neither is the site itself. The documents are largely produced by the team’s shared skills as part of the normal working cycle: requirements reviews generated from the code, worklogs written at each session’s close, help systems regenerated from the running application, and status that updates as work is checked in.
The cycle’s front end is where the governance lives. Incoming requests sit in Freshservice, and the list of items needing work is pulled from there onto the team’s monday.com board, a step done by hand today. A scheduled job on the Job Scheduler is planned to take it over, and it belongs there rather than in a skill, because the day-to-day working cycle never needs to touch Freshservice itself. Management gives its input on the board, and an item is worked only once it is approved; anything not approved stays where it is, in Freshservice and on the board. The detour is deliberate: work enters the cycle only through a surface management can see and steer, and the record of what was asked, what was approved, and what was delivered stays connected end to end.
Publishing works the same way: a single request during a working session, and the skill renders the document, uploads it, and records the revision, while the whole website rebuilds from source rather than being edited in place. A person decides what gets published and verifies what the skills produced; producing and maintaining the record is the machinery’s job, which is why the record stays current. And the machinery does not run loose: its ground rules live in the shared AI skills library, the same version-controlled set every machine pulls, which states what may run on its own and what waits to be asked.
The data-loss bug, kept in the record
The platform’s first serious bug destroyed data, and it is described on the platform itself rather than smoothed over.
Markdown source was originally stored at the document level. Publishing revision three of a document therefore overwrote the stored source of revision two, with no error and no warning, because the design had conflated the document with its latest version. By the time the shape of the bug was understood, one project’s earliest sources were permanently gone. The rendered HTML of those revisions survives; the Markdown that produced them does not.
The revision-scoped storage that exists now, one source file per revision, is the direct consequence. A habit is the other consequence: the platform’s own history page displays the loss as a fact about the platform, because a documentation system that hides its own worst incident has told every reader how it will handle theirs.
The outage that moved it to production hosting
Shortly after a routine publish, the site went completely unreachable. The timing pointed at the publish; the cause had nothing to do with it. The web server’s entire default site had gone into a stopped state, for reasons that were never fully explained, and a command-line restart brought it back.
The incident settled a question that had been open since the start: whether a documentation platform is infrastructure or a side project. It had been running on a development box, which is where side projects live. It was migrated in full to the same production application host that carries our staff-facing systems, the old instance was decommissioned the same day, and the platform has been treated as infrastructure since. The migration and the heaviest single day of commits, 20, landed on the same day.
A false finding, caught by the process it was reviewing
One document on the platform records the review methodology correcting itself. Self-correction is the property that makes the rest of the material trustworthy.
An earlier review pass had claimed that 9 database objects were missing and rated 4 review areas as partial on the strength of that claim. A more careful re-review found that 8 of the 9 existed all along. The finding was wrong, the correction is published, and the areas were re-rated. A review process that only ever adds findings should worry its readers. This one has demonstrated, in its own record, that a wrong finding gets reversed rather than defended.
The same review pipeline produced consequences outside itself: the 7 named findings on the Job Scheduler came from a review published here, and building the proposed tests for that review independently surfaced a genuine permissions bug.
Scale, measured
At the latest count, 7 projects publish to the platform, more than 30 documents in all. They include the requirements reviews for the Residential Client Portal (168 rows) and the Job Scheduler (64 rows across 10 areas), an engineering-standards section holding the review methodology, the monday.com integration conventions, and the platform’s own rulebook, and republished architecture and design documents from Sluice, Medallion Hub, and the Application Template, with Sluice alone contributing 15 documents in one pass.
A whole-site crawl after the migration found 46 pages and 567 internal links with zero broken. The complete footprint of the original server, measured before it was decommissioned, was 14.8 megabytes, a useful number against the instinct that documentation platforms need heavy machinery.
Publishing runs through a skill in the Shared AI Skills Library, so getting a document onto the platform is a request during a working session, not a procedure anyone must remember. The platform, in turn, is where the skills library’s own plain-language catalog is published, which makes the two projects each other’s evidence.
Timeline and effort
The build ran 48 commits in under three weeks, in bursts: 7 commits the first day, 13 the second, then concentrated pushes midway and 20 on the final day alongside the production migration.
Where it stands now
In production on the shared application host, carrying the group’s reviews, standards, and architecture documents. The next documents it receives will decide what it becomes: the current trajectory is that every substantial review and design decision across the projects on this site ends up with a URL here.