"A few months into working with AI agents on a documentation project, I'd noticed some inconsistency in agent behaviors and decided to do some digging. Turns out the AGENTS.md file in our repo — the one telling agents how to behave, where things were, and what to escalate — had grown to over 800 lines, and a few people (or likely their agents) had added rules independently, some subtly contradicting each other.

The agents weren't broken. They were following instructions that didn't serve them well.

In a previous post, I argued that agent configuration files are documentation and that their formats, structures, and purposes map directly to work technical communicators already do. That post covered the what: five doc types (project descriptions, agent definitions, orchestration patterns, skills, and plans/specs) and why writers are well-positioned to create them.

This post goes further. These files are internal documentation, full stop. They encode how your team actually works. And if you don't manage them with the same rigor you'd apply to any internal doc set, they'll degrade in the same ways: outdated content, conflicting guidance, and gaps nobody notices until something breaks."

https://instructionmanuel.com/agentic-docs-are-internal-docs

#TechnicalWriting #AI #AIAgents #AgentConfigs #Documentation #DocsAsCode #LLMs #GenerativeAI #Markdown

Indeed, we can't allow autopilot to head into a whirlwind...

"We may be doing docs-as-code, but docs are not code. Docs run on people, and people are a messy tangle of goals, skills, and emotions. When docs hit the brain, they meet varying expectations, knowledge levels, reading abilities, and needs. None of this can be reproduced or simplified to a single pattern, but good docs use structure and words wisely to produce the best possible linguistic shape that can land safely on most people’s heads. Only humans can decide whether that message is getting across in the right way.

Getting there is a balancing act between business needs, user needs, and your own. That’s the diplomatic tension that forces all good tech writers to slow down and consider all points of view in the room as if they were in the middle of a spaghetti Western standoff. Slowing down is a deliberate, necessary act in all crafts, and tech writing is no exception. No matter how fast LLMs can churn out drafts, they don’t understand the tension in tech writing, to which we’re adding AI itself as an additional consumer of docs.
(...)
The quality of the docs I produce is still high, I was saying. That’s because I’m not letting LLMs take the steering wheel, and because I’m building new habits around them: setting up guardrails, automating what can be automated, and keeping my hands on the decisions that matter. I can do that because I know what good docs look like, and because I’ve been doing this long enough to feel when something’s off. That intuition came from years of wrestling with products and watching users struggle with pages I thought were clear. AI can help me write faster. It cannot replace the slow accumulation of judgment that tells me when to stop."

https://passo.uno/real-cost-of-documentation/

#TechnicalWriting #SoftwareDocumentation #AI #DocsAsCode #GenerativeAI #LLMs #SoftwareDevelopment #AISlop #Programming #TechnicalCommunication #Documentation

"Test your documentation site against the Agent-Friendly Documentation Spec.

Agents don't use docs like humans. They hit truncation limits, get walls of CSS instead of content, can't follow cross-host redirects, and don't know about quality-of-life improvements like llms.txt or .md docs pages that would make life swell. Maybe this is because the industry has lacked guidance - until now.

afdocs runs 21 checks across 8 categories to evaluate how well your docs serve agent consumers. 10 are fully implemented; the rest return skip until completed."

https://www.npmjs.com/package/afdocs

#TechnicalWriting #SoftwareDocumentation #AI #AIAgents #Afdocs #Markdown #DocsAsCode #LLMSTXT

SDD (Spec-Driven Documentation) – фреймворк для разработки технической документации в репозитории

По мере роста сложности программных систем документация становится не “сопроводительным текстом”, а инженерным активом, она участвует в принятии решений, согласовании требований, проектировании архитектуры, тестировании и эксплуатации. Однако на практике документация часто создаётся разрозненно, несколькими авторами, в несогласованных форматах. Это приводит к потере целостности и росту транзакционных издержек на коммуникации. В такой распределённой среде параллельно растёт применение AI-ассистирования при подготовке технических материалов, что повышает требования к формализации процесса и контролю качества создаваемых артефактов [1]. В программных проектах техническая документация представляет собой совокупность различных артефактов – требований, сценариев, диаграмм, описаний архитектуры и данных – распределённых между участниками и стадиями жизненного цикла. В условиях активного уточнения целей и решений, особенно на стадии исследовательско-опытных работ (research and development, R&D; далее – R&D), такие артефакты развиваются неравномерно, одни быстро детализируются и пересматриваются, другие остаются на уровне ранних гипотез. Это приводит к утрате целостности документационного контура, возникают противоречия между документами, различается уровень абстракции, дрейфует терминология, а изменения становятся трудно сопоставимыми друг с другом. Одновременно ослабевает трассируемость и затрудняется восстановление причинно-следственной цепочки “исходные данные → допущение → решение → требование → сценарий/диаграмма → проверка”, что увеличивает стоимость ревью и повышает риск ошибочных инженерных выводов [2–5].

https://habr.com/ru/articles/996526/

#техническая_документация #docsascode #SpecDriven_Documentation #спецификации #трассируемость_требований #жизненный_цикл_артефактов #критерии_готовности #управление_неопределённостью #Architectural_Decision_Records #AIагент

More building with #hugo, it's not just for docs-sites, blogs and portfolios! I've been working on a project where I want to use Hugo to post a feed of in person events, so that people can add individual events to a calendar, learn about new events with RSS, etc. #events #docsascode #ssg #organizing

https://www.kevinrkuhl.com/blog/2026/02/generating-events-with-hugo/

Git в браузере. Расширяем возможности с помощью LFS

Привет, Хабр! Я Паша, разработчик

https://habr.com/ru/companies/gram_ax/articles/994384/

#git #libgit2 #lfs #webassembly #rust #ffi #emscripten #docsascode #opensource #localfirst

Как мы случайно сделали Semantic Wiki в Gramax

Всем привет! Меня зовут Катя, я развиваю Поехали!

https://habr.com/ru/companies/gram_ax/articles/993064/

#wiki #semantic_wiki #ontology #graph #knowledgebase #knowledge_management #база_знаний #управление_знаниями #управление_командой #docsascode

"Lint your docs like code: turn any style guide into enforceable rules with Vale and publish clear, consistent content every time.

Create consistent content that gives readers confidence with Vale, the open-source prose linter that helps you enforce your style guide automatically. Use battle-tested rules based on freely available, popular style guides, apply your brand’s terms with a custom vocabulary, and integrate Vale into your text editor, Git hooks, and CI pipeline. Catch typos and inclusive-language issues before they ship, and spend your energy on shaping ideas instead of fixing copy. Whether you’re a technical writer working in a docs-as-code environment, or a software engineer who occasionally writes, you’ll ship clean, consistent copy every time.

When you work on a content project, keeping things consistent can feel impossible. Typos slip through, people don’t follow style rules, and each contributor brings a slightly different voice. Vale helps you ensure consistency across your content.

You’ll start by catching typos as you learn how Vale works through hands-on examples. Then you’ll bring in community rules based on Google’s and Microsoft’s style guides. You’ll combine overlapping styles, adjust the rules to match your needs, and start shaping the experience you want readers to have. Then you’ll build your own rules from scratch and create a custom vocabulary to teach Vale to enforce your team’s voice and jargon. By the end, you’ll have a fully integrated, reusable style package that works in your editor, GitHub Actions, and your build systems. And while this book uses Markdown in its examples, you’ll be ready to apply everything you learned to reStructuredText, AsciiDoc, and even the comments in your source code.

Vale gives you a fast, reliable, and customizable way to keep your content consistent."

https://books.google.pt/books?id=nMabEQAAQBAJ

#TechnicalWriting #Vale #Markdown #DocsAsCode #StyleGuides #TechnicalCommunication

Новая жизнь репозитория: архитектурные решения для успешной документации

Привет, Хабр! Я Артём Клещев, технический писатель в СберТехе. Я пишу документацию к продукту Platform V DropApp — решению для управления контейнерными приложениями. Наша команда работает в парадигме Docs-as-Code. Мы столкнулись с проблемой: при каждом изменении продукта нам нужно было менять документацию сразу в нескольких репозиториях — для каждого исполнения продукта. Но мы нашли решение, как оптимизировать процесс. И хотим поделиться рекомендациями по ведению единого источника в Docs-as-Code — будет полезно тем, кто хочет шаблонизировать документацию и сэкономить время для творческих задач. В статье покажу, как построить удобную архитектуру репозитория продукта с применением шаблонов и MyST-разметки в парадигме Docs-as-Code. Расскажу, как вместо поддержки нескольких разрозненных комплектов документации создать библиотеку шаблонов с общим контентом. Надеюсь, что опыт нашей команды поможет вам избежать ошибок и лишних шагов.

https://habr.com/ru/companies/sberbank/articles/975836/

#сбертех #platform_v #dropapp #документация #документирование #docsascode