{"id":11791,"date":"2026-11-09T12:30:00","date_gmt":"2026-11-09T12:30:00","guid":{"rendered":"https:\/\/www.cotocus.com\/blog\/?p=11791"},"modified":"2026-11-09T12:30:00","modified_gmt":"2026-11-09T12:30:00","slug":"state-of-docs-named-reader","status":"publish","type":"post","link":"https:\/\/www.cotocus.com\/blog\/state-of-docs-named-reader\/","title":{"rendered":"State of Documentation: Teams Are Writing for a Named Reader"},"content":{"rendered":"

Walk into almost any engineering organisation today and you will find the same documentation story. There is a large wiki, a few well-loved pages, a graveyard of stale ones, and a quiet, widespread agreement that people mostly ask a colleague instead of reading. The interesting shift in the last few years is not a new tool. It is a change in how careful teams frame the job: from “document everything” to “write this page for a named person”. Here is a status check on that habit: what is driving it, and what a practical team can do with it without buying anything.<\/p>\n

Where documentation practice stands<\/h2>\n

The encyclopedia model is still dominant. Teams create a space, assign sections, and try to cover the system the way a reference book would. It feels responsible, and for some material, such as API references and policies, it is the right shape. But for everything involving a human making a decision or learning a new area, encyclopedic pages have a poor track record. Readers arrive with a specific problem, scan a long page for ten seconds, and leave to ask someone. Most practitioners will recognise that pattern without needing a survey to confirm it, and I will not pretend to quote a figure for it.<\/p>\n

The drivers behind the shift<\/h2>\n

Three pressures are pushing teams toward person-sized writing. The first is remote and hybrid work, which removed the habit of leaning over to ask a neighbour; documents now carry more of the teaching load. The second is churn in tooling, which makes comprehensive pages age quickly, while a short note for one reader is cheap to refresh. The third is a broader movement toward plain language in technical communication, which holds that clarity is a measurable courtesy rather than a stylistic nicety. None of these is new on its own. Together they have made the question “who exactly is this for?” harder to avoid.<\/p>\n

What a named-reader page looks like in practice<\/h2>\n

Take a machine learning team handing a trained model to a business analyst who will use its predictions in a weekly report. The encyclopedic version describes the architecture, the data pipeline and the evaluation methodology. The named-reader version opens with the analyst’s question: “Can I trust this number on Monday morning?” It explains what the output means, when it tends to be off, how to tell and whom to call. It runs a page and a half. Our full roadmap for data scientists and engineers working on model operations<\/a> covers the wider landscape; the analyst’s page is the small piece that sits at the end of it.<\/p>\n

The same trend in operations teams<\/h2>\n

Operations groups are applying the idea to runbooks, status messages and training. A message written for the executive who fields customer calls reads differently from one written for the engineer in the incident channel, and good teams now keep both. Training follows the pattern too. A short learning plan aimed at one trainee, such as a service-desk analyst moving toward automation work, tends to be completed more often than a catalogue of modules; for a worked example of structured training, see our write-up on the training a modern IT professional needs for automated operations<\/a>.<\/p>\n

Why the shift is slower than it should be<\/h2>\n

Habit is the main obstacle. Writing for everyone is comfortable because it cannot be wrong in a single way; any complaint can be answered with “it is in there somewhere”. A named-reader page can be wrong visibly, which is uncomfortable but useful. A second obstacle is ownership: encyclopedic spaces assign pages to systems, while person-sized notes need an owner who understands the reader. A third is metrics. Page views reward long, searchable pages, and they say little about whether the reader was helped. Organisations that measure the wrong thing keep getting the wrong writing.<\/p>\n

Practical moves for an ordinary team<\/h2>\n

You do not need a programme. Try three small things. First, add a line at the top of every new document that names its reader and the decision it supports. Second, when someone asks a question twice, write the answer for the person who asked rather than adding a section to the main wiki. Third, retire one long page per month by replacing it with two short ones aimed at different readers. After a quarter you will have a better feel for which pages earn their keep.<\/p>\n

What consultants and trainers are seeing<\/h2>\n

From the advisory side, the most common request is no longer “write us a policy” but “help our new leads understand what is expected of them in their first month”. That is a one-person question. Engagements that start from it tend to produce shorter, more practical material, and the clients’ staff actually open it. Whether this is a lasting trend or a phase is hard to say; the sample any single firm sees is small and biased toward teams already open to change. Treat the direction as plausible rather than proven.<\/p>\n

Where writers are putting this work<\/h2>\n

Beyond internal wikis, a growing number of practitioners keep a public notebook of what they have learned. Platforms differ; one example is iBlogUp, where authors post stories to a subdomain that is theirs and followers can subscribe by feed<\/a>. It describes itself as free, so verify that on its site. Public writing is a handy test bed, because the discipline of choosing a reader is the same whether the audience is a colleague or a stranger.<\/p>\n

Risks and limits worth naming<\/h2>\n

The approach has real limits. Some material genuinely needs to be comprehensive: safety procedures, legal obligations, API contracts. Do not trade those for friendly short notes. There is also a risk of fragmentation, with many small pages and no map. Solve it with a simple index that groups pages by reader rather than by system. And there is a human risk: choosing the wrong person, such as the loudest stakeholder, and writing for them at the expense of those who actually need help. Check your choice against the questions that really arrive.<\/p>\n

An example of the cost of skipping it<\/h2>\n

Picture a platform group that publishes a forty-section guide to its deployment process. A product engineer, new to the company, opens it on a Thursday because a release is due on Friday. She needs to know whether she can ship a small change without asking anyone. The answer exists, split across three sections and a footnote. She asks in chat instead, and a senior engineer spends ten minutes answering a question the guide technically covers. Repeat this across a year and the hidden cost is easy to imagine, even if no one logs it. A page titled for her, with her question as its first line, would have settled the matter in under a minute.<\/p>\n

Where this is heading<\/h2>\n

Expect the next few years to look less like a revolution than like a slow tidying. The tooling will keep changing, but the useful question will stay the same: who is this for, what are they worried about and how long will they give it? Teams that ask it by default will find their documentation shrinking and their onboarding speeding up. Teams that skip it will keep building wikis that people search once, distrust and abandon.<\/p>\n

If you want a quick temperature check, pick three pages your team links to most often and read each opening paragraph. Can you tell who it is for? If not, you have your first rewrite. Choose the person, say it out loud, and begin.<\/p>\n","protected":false},"excerpt":{"rendered":"

Engineering teams are moving from wikis that cover everything to pages written for one named reader. Here is what is driving it and how to try it.<\/p>\n","protected":false},"author":37,"featured_media":11792,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[147],"tags":[],"class_list":["post-11791","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-devops"],"yoast_head":"\nState of Documentation: Teams Are Writing for a Named Reader - Cotocus<\/title>\n<meta name=\"description\" content=\"How documentation is shifting from encyclopedic wikis to pages aimed at one named reader: the drivers, practical moves for teams, and the limits to watch.\" \/>\n<meta name=\"robots\" content=\"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1\" \/>\n<link rel=\"canonical\" href=\"https:\/\/www.cotocus.com\/blog\/state-of-docs-named-reader\/\" \/>\n<meta property=\"og:locale\" content=\"en_US\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"State of Documentation: Teams Are Writing for a Named Reader - Cotocus\" \/>\n<meta property=\"og:description\" content=\"How documentation is shifting from encyclopedic wikis to pages aimed at one named reader: the drivers, practical moves for teams, and the limits to watch.\" \/>\n<meta property=\"og:url\" content=\"https:\/\/www.cotocus.com\/blog\/state-of-docs-named-reader\/\" \/>\n<meta property=\"og:site_name\" content=\"Cotocus\" \/>\n<meta property=\"article:published_time\" content=\"2026-11-09T12:30:00+00:00\" \/>\n<meta property=\"og:image\" content=\"https:\/\/www.cotocus.com\/blog\/wp-content\/uploads\/2026\/11\/b2a-banner-123235-banner.png\" \/>\n\t<meta property=\"og:image:width\" content=\"1200\" \/>\n\t<meta property=\"og:image:height\" content=\"630\" \/>\n\t<meta property=\"og:image:type\" content=\"image\/png\" \/>\n<meta name=\"author\" content=\"Nikhil Farooqui\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<meta name=\"twitter:label1\" content=\"Written by\" \/>\n\t<meta name=\"twitter:data1\" content=\"Nikhil Farooqui\" \/>\n\t<meta name=\"twitter:label2\" content=\"Est. reading time\" \/>\n\t<meta name=\"twitter:data2\" content=\"6 minutes\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\\\/\\\/schema.org\",\"@graph\":[{\"@type\":\"Article\",\"@id\":\"https:\\\/\\\/www.cotocus.com\\\/blog\\\/state-of-docs-named-reader\\\/#article\",\"isPartOf\":{\"@id\":\"https:\\\/\\\/www.cotocus.com\\\/blog\\\/state-of-docs-named-reader\\\/\"},\"author\":{\"name\":\"Nikhil Farooqui\",\"@id\":\"https:\\\/\\\/www.cotocus.com\\\/blog\\\/#\\\/schema\\\/person\\\/419007bef27e8d85890550d783b96c50\"},\"headline\":\"State of Documentation: Teams Are Writing for a Named Reader\",\"datePublished\":\"2026-11-09T12:30:00+00:00\",\"mainEntityOfPage\":{\"@id\":\"https:\\\/\\\/www.cotocus.com\\\/blog\\\/state-of-docs-named-reader\\\/\"},\"wordCount\":1266,\"commentCount\":0,\"image\":{\"@id\":\"https:\\\/\\\/www.cotocus.com\\\/blog\\\/state-of-docs-named-reader\\\/#primaryimage\"},\"thumbnailUrl\":\"https:\\\/\\\/www.cotocus.com\\\/blog\\\/wp-content\\\/uploads\\\/2026\\\/11\\\/b2a-banner-123235-banner.png\",\"articleSection\":[\"DevOps\"],\"inLanguage\":\"en-US\",\"potentialAction\":[{\"@type\":\"CommentAction\",\"name\":\"Comment\",\"target\":[\"https:\\\/\\\/www.cotocus.com\\\/blog\\\/state-of-docs-named-reader\\\/#respond\"]}]},{\"@type\":\"WebPage\",\"@id\":\"https:\\\/\\\/www.cotocus.com\\\/blog\\\/state-of-docs-named-reader\\\/\",\"url\":\"https:\\\/\\\/www.cotocus.com\\\/blog\\\/state-of-docs-named-reader\\\/\",\"name\":\"State of Documentation: Teams Are Writing for a Named Reader - Cotocus\",\"isPartOf\":{\"@id\":\"https:\\\/\\\/www.cotocus.com\\\/blog\\\/#website\"},\"primaryImageOfPage\":{\"@id\":\"https:\\\/\\\/www.cotocus.com\\\/blog\\\/state-of-docs-named-reader\\\/#primaryimage\"},\"image\":{\"@id\":\"https:\\\/\\\/www.cotocus.com\\\/blog\\\/state-of-docs-named-reader\\\/#primaryimage\"},\"thumbnailUrl\":\"https:\\\/\\\/www.cotocus.com\\\/blog\\\/wp-content\\\/uploads\\\/2026\\\/11\\\/b2a-banner-123235-banner.png\",\"datePublished\":\"2026-11-09T12:30:00+00:00\",\"author\":{\"@id\":\"https:\\\/\\\/www.cotocus.com\\\/blog\\\/#\\\/schema\\\/person\\\/419007bef27e8d85890550d783b96c50\"},\"description\":\"How documentation is shifting from encyclopedic wikis to pages aimed at one named reader: the drivers, practical moves for teams, and the limits to watch.\",\"breadcrumb\":{\"@id\":\"https:\\\/\\\/www.cotocus.com\\\/blog\\\/state-of-docs-named-reader\\\/#breadcrumb\"},\"inLanguage\":\"en-US\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\\\/\\\/www.cotocus.com\\\/blog\\\/state-of-docs-named-reader\\\/\"]}]},{\"@type\":\"ImageObject\",\"inLanguage\":\"en-US\",\"@id\":\"https:\\\/\\\/www.cotocus.com\\\/blog\\\/state-of-docs-named-reader\\\/#primaryimage\",\"url\":\"https:\\\/\\\/www.cotocus.com\\\/blog\\\/wp-content\\\/uploads\\\/2026\\\/11\\\/b2a-banner-123235-banner.png\",\"contentUrl\":\"https:\\\/\\\/www.cotocus.com\\\/blog\\\/wp-content\\\/uploads\\\/2026\\\/11\\\/b2a-banner-123235-banner.png\",\"width\":1200,\"height\":630},{\"@type\":\"BreadcrumbList\",\"@id\":\"https:\\\/\\\/www.cotocus.com\\\/blog\\\/state-of-docs-named-reader\\\/#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Home\",\"item\":\"https:\\\/\\\/www.cotocus.com\\\/blog\\\/\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"State of Documentation: Teams Are Writing for a Named Reader\"}]},{\"@type\":\"WebSite\",\"@id\":\"https:\\\/\\\/www.cotocus.com\\\/blog\\\/#website\",\"url\":\"https:\\\/\\\/www.cotocus.com\\\/blog\\\/\",\"name\":\"Cotocus\",\"description\":\"Shaping Tomorrow\u2019s Tech Today\",\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":{\"@type\":\"EntryPoint\",\"urlTemplate\":\"https:\\\/\\\/www.cotocus.com\\\/blog\\\/?s={search_term_string}\"},\"query-input\":{\"@type\":\"PropertyValueSpecification\",\"valueRequired\":true,\"valueName\":\"search_term_string\"}}],\"inLanguage\":\"en-US\"},{\"@type\":\"Person\",\"@id\":\"https:\\\/\\\/www.cotocus.com\\\/blog\\\/#\\\/schema\\\/person\\\/419007bef27e8d85890550d783b96c50\",\"name\":\"Nikhil Farooqui\",\"image\":{\"@type\":\"ImageObject\",\"inLanguage\":\"en-US\",\"@id\":\"https:\\\/\\\/secure.gravatar.com\\\/avatar\\\/d855702dac00a5af0405bb329101be495718d611233e52c86fe360c8fca6f6dc?s=96&d=mm&r=g\",\"url\":\"https:\\\/\\\/secure.gravatar.com\\\/avatar\\\/d855702dac00a5af0405bb329101be495718d611233e52c86fe360c8fca6f6dc?s=96&d=mm&r=g\",\"contentUrl\":\"https:\\\/\\\/secure.gravatar.com\\\/avatar\\\/d855702dac00a5af0405bb329101be495718d611233e52c86fe360c8fca6f6dc?s=96&d=mm&r=g\",\"caption\":\"Nikhil Farooqui\"},\"url\":\"https:\\\/\\\/www.cotocus.com\\\/blog\\\/author\\\/nikhil-farooqui\\\/\"}]}<\/script>\n<!-- \/ Yoast SEO plugin. -->","yoast_head_json":{"title":"State of Documentation: Teams Are Writing for a Named Reader - Cotocus","description":"How documentation is shifting from encyclopedic wikis to pages aimed at one named reader: the drivers, practical moves for teams, and the limits to watch.","robots":{"index":"index","follow":"follow","max-snippet":"max-snippet:-1","max-image-preview":"max-image-preview:large","max-video-preview":"max-video-preview:-1"},"canonical":"https:\/\/www.cotocus.com\/blog\/state-of-docs-named-reader\/","og_locale":"en_US","og_type":"article","og_title":"State of Documentation: Teams Are Writing for a Named Reader - Cotocus","og_description":"How documentation is shifting from encyclopedic wikis to pages aimed at one named reader: the drivers, practical moves for teams, and the limits to watch.","og_url":"https:\/\/www.cotocus.com\/blog\/state-of-docs-named-reader\/","og_site_name":"Cotocus","article_published_time":"2026-11-09T12:30:00+00:00","og_image":[{"width":1200,"height":630,"url":"https:\/\/www.cotocus.com\/blog\/wp-content\/uploads\/2026\/11\/b2a-banner-123235-banner.png","type":"image\/png"}],"author":"Nikhil Farooqui","twitter_card":"summary_large_image","twitter_misc":{"Written by":"Nikhil Farooqui","Est. reading time":"6 minutes"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"Article","@id":"https:\/\/www.cotocus.com\/blog\/state-of-docs-named-reader\/#article","isPartOf":{"@id":"https:\/\/www.cotocus.com\/blog\/state-of-docs-named-reader\/"},"author":{"name":"Nikhil Farooqui","@id":"https:\/\/www.cotocus.com\/blog\/#\/schema\/person\/419007bef27e8d85890550d783b96c50"},"headline":"State of Documentation: Teams Are Writing for a Named Reader","datePublished":"2026-11-09T12:30:00+00:00","mainEntityOfPage":{"@id":"https:\/\/www.cotocus.com\/blog\/state-of-docs-named-reader\/"},"wordCount":1266,"commentCount":0,"image":{"@id":"https:\/\/www.cotocus.com\/blog\/state-of-docs-named-reader\/#primaryimage"},"thumbnailUrl":"https:\/\/www.cotocus.com\/blog\/wp-content\/uploads\/2026\/11\/b2a-banner-123235-banner.png","articleSection":["DevOps"],"inLanguage":"en-US","potentialAction":[{"@type":"CommentAction","name":"Comment","target":["https:\/\/www.cotocus.com\/blog\/state-of-docs-named-reader\/#respond"]}]},{"@type":"WebPage","@id":"https:\/\/www.cotocus.com\/blog\/state-of-docs-named-reader\/","url":"https:\/\/www.cotocus.com\/blog\/state-of-docs-named-reader\/","name":"State of Documentation: Teams Are Writing for a Named Reader - Cotocus","isPartOf":{"@id":"https:\/\/www.cotocus.com\/blog\/#website"},"primaryImageOfPage":{"@id":"https:\/\/www.cotocus.com\/blog\/state-of-docs-named-reader\/#primaryimage"},"image":{"@id":"https:\/\/www.cotocus.com\/blog\/state-of-docs-named-reader\/#primaryimage"},"thumbnailUrl":"https:\/\/www.cotocus.com\/blog\/wp-content\/uploads\/2026\/11\/b2a-banner-123235-banner.png","datePublished":"2026-11-09T12:30:00+00:00","author":{"@id":"https:\/\/www.cotocus.com\/blog\/#\/schema\/person\/419007bef27e8d85890550d783b96c50"},"description":"How documentation is shifting from encyclopedic wikis to pages aimed at one named reader: the drivers, practical moves for teams, and the limits to watch.","breadcrumb":{"@id":"https:\/\/www.cotocus.com\/blog\/state-of-docs-named-reader\/#breadcrumb"},"inLanguage":"en-US","potentialAction":[{"@type":"ReadAction","target":["https:\/\/www.cotocus.com\/blog\/state-of-docs-named-reader\/"]}]},{"@type":"ImageObject","inLanguage":"en-US","@id":"https:\/\/www.cotocus.com\/blog\/state-of-docs-named-reader\/#primaryimage","url":"https:\/\/www.cotocus.com\/blog\/wp-content\/uploads\/2026\/11\/b2a-banner-123235-banner.png","contentUrl":"https:\/\/www.cotocus.com\/blog\/wp-content\/uploads\/2026\/11\/b2a-banner-123235-banner.png","width":1200,"height":630},{"@type":"BreadcrumbList","@id":"https:\/\/www.cotocus.com\/blog\/state-of-docs-named-reader\/#breadcrumb","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https:\/\/www.cotocus.com\/blog\/"},{"@type":"ListItem","position":2,"name":"State of Documentation: Teams Are Writing for a Named Reader"}]},{"@type":"WebSite","@id":"https:\/\/www.cotocus.com\/blog\/#website","url":"https:\/\/www.cotocus.com\/blog\/","name":"Cotocus","description":"Shaping Tomorrow\u2019s Tech Today","potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/www.cotocus.com\/blog\/?s={search_term_string}"},"query-input":{"@type":"PropertyValueSpecification","valueRequired":true,"valueName":"search_term_string"}}],"inLanguage":"en-US"},{"@type":"Person","@id":"https:\/\/www.cotocus.com\/blog\/#\/schema\/person\/419007bef27e8d85890550d783b96c50","name":"Nikhil Farooqui","image":{"@type":"ImageObject","inLanguage":"en-US","@id":"https:\/\/secure.gravatar.com\/avatar\/d855702dac00a5af0405bb329101be495718d611233e52c86fe360c8fca6f6dc?s=96&d=mm&r=g","url":"https:\/\/secure.gravatar.com\/avatar\/d855702dac00a5af0405bb329101be495718d611233e52c86fe360c8fca6f6dc?s=96&d=mm&r=g","contentUrl":"https:\/\/secure.gravatar.com\/avatar\/d855702dac00a5af0405bb329101be495718d611233e52c86fe360c8fca6f6dc?s=96&d=mm&r=g","caption":"Nikhil Farooqui"},"url":"https:\/\/www.cotocus.com\/blog\/author\/nikhil-farooqui\/"}]}},"_links":{"self":[{"href":"https:\/\/www.cotocus.com\/blog\/wp-json\/wp\/v2\/posts\/11791","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.cotocus.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.cotocus.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.cotocus.com\/blog\/wp-json\/wp\/v2\/users\/37"}],"replies":[{"embeddable":true,"href":"https:\/\/www.cotocus.com\/blog\/wp-json\/wp\/v2\/comments?post=11791"}],"version-history":[{"count":1,"href":"https:\/\/www.cotocus.com\/blog\/wp-json\/wp\/v2\/posts\/11791\/revisions"}],"predecessor-version":[{"id":11859,"href":"https:\/\/www.cotocus.com\/blog\/wp-json\/wp\/v2\/posts\/11791\/revisions\/11859"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/www.cotocus.com\/blog\/wp-json\/wp\/v2\/media\/11792"}],"wp:attachment":[{"href":"https:\/\/www.cotocus.com\/blog\/wp-json\/wp\/v2\/media?parent=11791"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.cotocus.com\/blog\/wp-json\/wp\/v2\/categories?post=11791"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.cotocus.com\/blog\/wp-json\/wp\/v2\/tags?post=11791"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}