Are You Still Paying for Docs?
Beautiful pages can belong to the project. What is the subscription still buying?
Published
The New York Times set its last hot-metal edition in July 1978.
The Linotype had entered newspaper production in 1886, turning a compositor’s keystrokes into whole lines of metal type. At the Times, the change in 1978 replaced the last 61 Linotype machines with a computerised process.1 A newspaper still needed words, pictures, editors and judgement. It no longer needed that room full of machines to put the words on a page.
The same uncomfortable question is coming for documentation platforms: how much of the bill pays for work that still needs doing, and how much pays for machinery we no longer need to rent?
For much of the last decade, paying a docs platform was a rational answer to a real problem. Who is going to make this look like a proper publication? Who is going to keep it working? The bundle was a renderer, a theme, search, a sidebar tree, a few clever components, a domain. Assembling and maintaining all that took time. A good platform gave an engineering team something it could be proud to send to a customer.
That was worth money. The mistake is assuming the same bundle must remain worth the same money indefinitely.
The polish floor moved
PageMaker arrived on the Macintosh in 1985. Alongside the LaserWriter and PostScript, it brought page layout onto the desktop.2 This was a later stage of the typesetting upheaval, not the technology that retired the Times’ hot metal seven years earlier. The distinction matters because the change came in layers: first a different production process, then access to that process for people who had never owned a typesetting shop.
Neither development made everyone a designer. It changed who could afford to put a design into print.
Open source documentation tooling has had its own version of that shift. A project can have clear type, useful search, good navigation and a reference generated from its own source without buying a hosted publishing subscription. Sourcey is part of that work. So are the other people building tools for publishing on the open web.
I care a great deal about how it looks. Beautiful docs are part of the reason to build this stuff. A project with years of engineering behind it deserves a front door that makes you want to walk through. It deserves pages that still look considered when you open a complicated type or read a long guide on a phone.
What has become cheaper is getting a capable renderer. Taste has not become a config flag. A model can generate twenty sidebar treatments before lunch; someone still has to choose the one that helps a reader find their way. The craft moves, as it did when designers stopped needing hot metal. It does not evaporate.
The dialect is the lock-in
A hundred Markdown files in Git can look reassuringly portable. Open one. How much of the page depends on components that only the current publishing system understands?
Callouts, tabbed code groups, accordions, cards, frontmatter conventions controlling navigation: every one can be a stake driven into the docs that has to be pulled out before the project can leave. Not every custom component is a trap. Some have straightforward open equivalents. But the cost belongs in the decision, because it grows one apparently harmless page at a time.
A hundred pages in a vendor-specific dialect can mean a hundred pages to inspect during a move. What looked like a visual choice has become a renewal clause embedded in the syntax.
The revealing test is a complicated page. Export the guide with tabs, an uploaded image, a reference link and a warning box. Build it elsewhere. The exit drill is worth doing before you need it. If the words travel but the page falls apart, you have found the part of the product you are still renting.
The second reader arrives
A human opens the docs and sees the typography, the spacing, the care. An agent may retrieve the same URL and work from extracted text. A beautifully drawn distinction can vanish if it was communicated only through position or colour.
That does not make design irrelevant. It means the document has another way to fail.
A reference can look immaculate while leaving an agent unable to tell whether a field is optional, whether a token belongs in a header, or which version an example describes. Conversely, a flat text dump can contain every word and make a human wish they had chosen another library. We need to care about both readers. Your Docs Have a Second Reader Now goes into the practical work.
The useful shift is that presentation and meaning can be inspected separately. Open the page. Then read the extracted content. Does the sentence that changes the answer survive? Can the reader reach the definition behind the example? Can you identify the release those words describe?
A subscription can help deliver that. It cannot make it true by appearing on an invoice.
What is still worth paying for?
A writer who understands the product. An editor who spots the missing explanation. A publishing workflow that lets the people with the knowledge contribute it. Access controls the team actually needs. Someone responsible for keeping the site available when your own engineers have other work to do.
Those are services with a job to perform. Pay for them when they earn their place.
The question is whether the current bill buys those things or merely keeps a renderer switched on. If your team already writes in Git, reviews through pull requests, generates the reference in CI and hosts other static sites, the platform may be duplicating work you already do. If the docs are maintained by people who need a shared editor and a managed review process, taking those away has a cost too.
There is no virtue in cancelling a subscription and quietly assigning a teammate a second job. There is also no virtue in paying forever because nobody has tried building the site somewhere else.
The new signal
A beautiful reference should make the engineering visible. The examples should work. The links should lead somewhere useful. The language should tell you what the author knows about using the thing, including the small condition that would otherwise cost you an afternoon.
That is where a serious project can distinguish itself. The typeface, the writing and the API examples should feel like somebody made decisions, because somebody did. Cheap generation makes that judgement more valuable: it gives us much more material to choose from and far less excuse for shipping the first acceptable version.
Ownership matters here. The project should be able to keep the design it is proud of, revise its own explanations and move its published site without losing its identity. Having the source, the build and the finished output gives it that option. A platform may make the work easier; it should not make departure mean starting again.
After the moat
Open the last invoice from whichever platform the project is on. Beside it, write down what the service actually does for the people who write and read the docs. Then try a small independent build and see what it would take to keep doing those things.
Keep the subscription if the answer justifies it. But make the renderer earn its place again. “It makes the pages look professional” used to settle the discussion. Now the project can own beautiful pages, and the bill needs a better explanation.
The moat around rendering is gone. Nobody has told the invoicing system.