Archiboard

Set K · Craft & Judgment

Reading Microsoft docs like an architect

The Architecture Center, the product docs and the Well-Architected Framework answer three different questions. Read the limits page first, check the date, and go to the samples repo when the words stop making sense.

In August 2020 I spent a full day designing a tenant onboarding flow around a feature of Azure SQL that the documentation described in detail, with code samples and a diagram. Late that afternoon I found the small box at the top of the page: the feature was in preview, in two regions, neither of them in Western Europe. The page was accurate. I had read it in the wrong order.

Since then I read Microsoft documentation the way I read a building specification: limits first, then the date, then the prose. This sounds joyless. It has saved me perhaps a month a year, and it has changed which pages I open first, because the documentation is not one thing. It is at least four layers written by different people for different questions, and knowing which layer you are on tells you how much to trust it.

What follows is how I sort the layers, the order I read a page in, and what to do when the docs and the product disagree.

Four layers, four questions

The Well-Architected Framework answers "what does good look like". It is organised around five pillars (reliability, security, cost, operational excellence, performance) and it is opinionated in a way the rest of the documentation is not. It will tell you that a multi-tenant product should meter per-tenant consumption; it will not tell you how. I read it when I am deciding, not when I am building. Its guidance for multi-tenant workloads, added in 2024, is the closest thing to a peer review I can get without hiring one.

The Azure Architecture Center answers "how do these pieces fit together". Reference architectures, the multitenant guide, the design patterns catalogue. This is where the tenancy models page lives, and the noisy-neighbour antipattern, and the sharding pattern. The Center is written by the patterns-and-practices people and it dates faster than the framework, because it names services and services change. A reference architecture from 2019 with Azure AD B2C in it is a historical document now.

The product documentation answers "what does this service actually do". Every Azure service and every .NET library has its own docs tree, and it is the only layer that is authoritative about behaviour. It is also the layer with the least opinion. The Azure SQL docs will explain elastic pools in detail and say almost nothing about whether you should use them for tenants. That is not their job.

Underneath all of that is the samples repository on GitHub, which answers "does this actually compile". The dotnet/samples repository and the per-product sample trees are where the words in the docs meet a csproj. When a page describes an API and I cannot make it behave, the sample usually shows the one line of setup the page left out.

The four layers of Microsoft documentation and the question each answers opinion Well-Architected Framework five pillars, workload guides Azure Architecture Center patterns, reference architectures behaviour Product documentation one tree per service and library Samples repository github.com/dotnet/samples what does good look like read when deciding how do the pieces fit together read when combining services what does it actually do read when building does it compile read when the page stops making sense limits, date, considerations read these before the overview
Fig. 1. Four layers, four questions. The top two carry opinion and date slowly; the bottom two carry behaviour and are the only ones to trust about what a service does today.

Limits page first, then the date

Every Azure service has a page called something like "limits, quotas and constraints", and there is one page that aggregates all of them for a subscription. I read it before the overview. The overview will tell me what the service is for; the limits page will tell me whether it can do it for 900 tenants. A storage account has a request rate ceiling. A Service Bus namespace has a topic count. Azure SQL has a database-per-server limit that is higher than you think and a login rate that is lower. None of these appear in the overview, and all of them decide whether the design survives.

Then the date. Every page has a date at the top, and many .NET pages have a version selector as well. I check both before I read a paragraph. A page dated 2019 about ASP.NET Core hosting is describing IWebHostBuilder and Startup.cs, and it is still correct for a codebase that has not moved. A page dated last month about the same topic is describing WebApplication.CreateBuilder. Both are true. The version selector matters more than the date: an ASP.NET Core page set to 3.1 will happily show you an API that no longer exists in 9, without warning, because you asked for 3.1.

A note on the addresses themselves. When I first wrote this sheet the site was docs.microsoft.com, and in 2022 it became learn.microsoft.com. The redirects mostly work, the anchors mostly do not, and about half the links in my notes died quietly over a weekend. I now save the page title next to the URL, which costs two seconds and has saved me a great deal of searching for a paragraph I remembered word for word and could not find.

Then, and only then, the prose. And within the prose, the "considerations" section before the "how to" section. Almost every product page has one, usually near the bottom, and it is where the honest sentences live: "this feature is not supported with private endpoints", "changing this setting requires recreating the resource". The how-to section is written to succeed. The considerations section is written by someone who has seen it fail.

Following the samples repo

I keep a local clone of dotnet/samples and of the docs repositories for ASP.NET Core and EF Core, and I pull them about once a month. This is not for reading; it is for grepping. When a documentation page shows a fragment and I want the whole file, the fragment usually comes from a sample in one of those repositories, and the sample has the using statements and the project file that the page cut for length.

The samples also tell you what Microsoft is actually testing. If a feature has a sample that has been updated for the current release, someone ran it. If the only sample is three years old, the feature works, probably, but nobody has looked at it recently, and you will be the one who finds out what changed.

When the docs are ahead, and when behind

The documentation runs ahead of the product in two predictable places. Preview features get full pages before they are available in every region, and the page will say so in a box near the top that is easy to skip, as I learned in 2020. And .NET documentation is written against the release branch, so pages for the next major version appear in preview form months before the release; a version selector set to "10.0 (preview)" in the summer of 2025 was describing APIs that changed twice before they shipped.

It runs behind in two places as well. Service retirements: a feature gets a retirement notice on one page and keeps its full documentation on ten others for a year or more. The Elastic Database tools for Azure SQL were in this state when I wrote the first version of this sheet, and I designed against them before I found the notice. And behaviour changes in patch releases: the .NET runtime ships servicing updates monthly, and a patch that changes a default (a timeout, a connection pool size) will be in the release notes on GitHub weeks before the conceptual page catches up. When something changes under you and the docs say it should not have, the release notes are the next place to look.

The order I read in today

Limits, date, version selector, considerations, then the page. Then the sample, if the page has one. Then the framework, if I am still unsure whether I should be doing this at all. It is slower on the first page and faster on every page after, because most pages turn out to be answering a question I did not have.

Drawn from