#docsascode — Public Fediverse posts

"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

"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

"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

"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

"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 #командная_документация

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

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

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

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

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

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

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

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

Как мы потеряли 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

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

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

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

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

"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

"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

"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

"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агент

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агент

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агент

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агент

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Как мы случайно сделали 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

"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

"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

"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

"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

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

Привет, Хабр! Я Артём Клещев, технический писатель в СберТехе. Я пишу документацию к продукту 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

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

Привет, Хабр! Я Артём Клещев, технический писатель в СберТехе. Я пишу документацию к продукту 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

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

Привет, Хабр! Я Артём Клещев, технический писатель в СберТехе. Я пишу документацию к продукту 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

"At my current job, I've built a CLI tool that has over 20 different commands that help my team with doc ops and content quality. We frequently add, remove, and refine commands as our approach to documentation matures and our tooling changes. Our CLI was built to work with our docs repo, and has tools that let us do things like:

- Validate all our arbitrary frontmatter
- Generate card components for individual pages from frontmatter
- Regenerate our custom Vale Views
- Run a bunch of git commands for reporting purposes
- Build a changelog for our Fern Definition
- Summarize changes on a branch compared to main (to help draft release notes)
- Extract and format a list of all our public endpoints from our Fern Definition
- Generate a list of slugs and their associated filenames
- Regenerate all D2 diagrams
- Preflight checks that run all of our doc quality checks
- So much more

Some of our commands are just thin wrappers for commands for other tools we use (like Fern, Vale, git, and Linkinator). Some of our commands are just wrappers for bundles of our homegrown scripts. There aren't any hard rules for building your own internal CLI tooling. I just happened to bundle it all up into a CLI tool because that's what made sense for my team. Do what makes sense for your team."

https://docsgoblin.com/blog/25-12-03-building-tooling.html

#TechnicalWriting #DocsAsCode #Automation #SoftwareDocumentation #CLI #DocOps #Git #Vale

Как мы с ИИ перезапустили документацию Bitrix Framework и сэкономили 400 часов

Привет! Меня зовут Марина Павлова, я технический писатель в отделе документации 1С-Битрикс. В этой статье я расскажу, как мы полностью переделали документацию по Bitrix Framework и как команде из двух человек удалось выпустить доку за 9 месяцев с помощью ИИ.

https://habr.com/ru/companies/bitrix/articles/959134/

#bitrix #framework #документация #bitrix_программирование #documentation #docsascode #docs_as_code #docs #ии #нейросети

Как мы с ИИ перезапустили документацию Bitrix Framework и сэкономили 400 часов

Привет! Меня зовут Марина Павлова, я технический писатель в отделе документации 1С-Битрикс. В этой статье я расскажу, как мы полностью переделали документацию по Bitrix Framework и как команде из двух человек удалось выпустить доку за 9 месяцев с помощью ИИ.

https://habr.com/ru/companies/bitrix/articles/959134/

#bitrix #framework #документация #bitrix_программирование #documentation #docsascode #docs_as_code #docs #ии #нейросети

Как мы с ИИ перезапустили документацию Bitrix Framework и сэкономили 400 часов

Привет! Меня зовут Марина Павлова, я технический писатель в отделе документации 1С-Битрикс. В этой статье я расскажу, как мы полностью переделали документацию по Bitrix Framework и как команде из двух человек удалось выпустить доку за 9 месяцев с помощью ИИ.

https://habr.com/ru/companies/bitrix/articles/959134/

#bitrix #framework #документация #bitrix_программирование #documentation #docsascode #docs_as_code #docs #ии #нейросети

Как мы с ИИ перезапустили документацию Bitrix Framework и сэкономили 400 часов

Привет! Меня зовут Марина Павлова, я технический писатель в отделе документации 1С-Битрикс. В этой статье я расскажу, как мы полностью переделали документацию по Bitrix Framework и как команде из двух человек удалось выпустить доку за 9 месяцев с помощью ИИ.

https://habr.com/ru/companies/bitrix/articles/959134/

#bitrix #framework #документация #bitrix_программирование #documentation #docsascode #docs_as_code #docs #ии #нейросети

"Vale MCP Server

A Model Context Protocol (MCP) server that integrates Vale prose linting into AI coding assistants like Claude Code and Gemini command-line tool.

Overview

This MCP server provides AI assistants with the ability to check files for style and grammar issues using Vale's powerful linting engine. It automatically discovers Vale configuration files and provides formatted, actionable feedback about writing quality.

Features

✅ File linting: Check any text file for style issues with Vale.

🔍 Smart config discovery: Automatically finds .vale.ini files using Vale's native upward search.

🎯 Configuration priority: Supports VALE_CONFIG_PATH environment variable for explicit config.

📊 Rich formatting: Returns markdown-formatted results with emojis and severity grouping.

🛡️ Graceful degradation: Provides helpful installation guidance when Vale isn't installed.

🐛 Debug mode: Optional debug logging for troubleshooting."

https://github.com/theletterf/vale-mcp-server

#Vale #Linting #Markdown #TechnicalWriting #DocsAsCode #SoftwareDocumentation #MCP #MCPServer #StyleGuide

"A documentation platform is a product that provides capabilities—some free; some paid—for a range of activities, like authoring, editing, collaborating, monitoring, building, deploying, and publishing documentation.

Docs-as-code platforms are more common these days, as more people can code or leverage systems like AI that help them code. Traditionally, authoring to publication might take place locally, or via a software product that offered manual versioning, limited collaboration, and limited-to-no support for documentation pipeline automation, like setting up a CI/CD pipeline to deploy health documentation when the `main` has a new commit. If you remember the yesteryears of authoring, products like Subversion and TortoiseSVN may come to mind.

The platforms I’m writing about today are modern and all offer some type of free documentation generation, usually through static site generation; however, outside of what’s provided out of the box, there are notable differences between what’s provided for free and what’s provided at cost.

My goal for this article is to point out some core differences across add-ons, features, and enterprise-level support across these documentation platforms so that you choose the platform that’s best for you and your documentation readers.

For this article, I researched Fern, Mintlify, ReadMe, and Redocly."

https://www.copytree.io/post/choosing-modern-docs-platform

#TechnicalWriting #SoftwareDocumentation #APIDocumentation #APIs #SoftwareDevelopment #Programming #DocsAsCode

"Opening up the docs roadmap is harder to do when software projects are steered by for-profit companies, because it’s part of wider strategic conversation that might occur behind closed doors, but it’s not impossible. If your documentation is already open source, as well as issues and epics, you can decide to host biweekly or monthly open calls with internal and external docs contributors to get their feedback and ideas, which is an interesting communal complement to UX research.

To reach this level of community contribution requires you to gradually relinquish control. Your role shifts from gatekeeper to orchestrator, from sole author to chief editor of a collaborative narrative. This is where documentation transcends mere utility and becomes something closer to folklore: a living, breathing testament to how real people engage with your creation."

https://passo.uno/docs-contribution-journey/

#TechnicalWriting #TechnicalDocumentation #DocsAsCode #SoftwareDocumentation #OpenSource #FLOSS #SoftwareDevelopment