От хаоса к порядку: как и зачем мы перешли на модифицированную архитектуру ведения Git

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

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

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

"Back in 2024 I wrote that AI helps me remove boring work at the margins. This is fine for a lone writer, but how to scale this to an entire team of technical writers? How to make the system helpful but not intrusive? These are all questions I’m starting to answer now, partly through experimentation, but also through dialogue with practitioners and colleagues. One answer I’m testing these days relies on GitHub Agentic Workflows.

Following Four modes of AI-augmented technical writing, I thought of a way of distributing tooling effort across all modes through a tiered system where each level holds a different relationship with the writer. The result is four tiers: intake, local assistance, automated governance, and an MCP server that provides reliable knowledge to all. The idea is that AI assists the writer not just while writing, but also before and after they work on docs."

https://passo.uno/agentic-workflows-for-docs/

#TechnicalWriting #AI #GenerativeAI #LLMs #AIAgents #AgenticAI #AgenticWorkflows #SoftwareDocumentation #GitHub #DocsAsCode

Как мы потеряли GitBook за 5 минут и нашли Gramax — open-source альтернативу, которую теперь используем сами

Один клик — и ваша документация может исчезнуть. Именно так и произошло с нами. Поэтому мы нашли open-source альтернативу, где данными владеем только мы — и никакой регион это не изменит.

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

#Gramax #GitBook #open_source #документация #docsascode #Markdown #Git #стартап #альтернатива_GitBook #командная_документация

I've been testing #zensical since I will have to migrate off of #mkdocs and #mkdocsmaterial.

Across 3 sites, I only had to change one line in the yaml files and run `zensical` instead of `mkdocs`. Total potential migration time for 3 sites, 10 minutes.

Why potential and not complete? Pending blog and OpenAPI spec support. Once those are released, I can finish testing and migrate.

@squidfunk looking good so far. Thanks!

#technology #tech #indieweb #blog #technicalwriting #docs #docsascode

"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/