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

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

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

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

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

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

It's not very often that GPT5 surprises me. In fact, I would say it's quite rare when compared to Gemini 2.5 Pro. But this time, it really, really surprised.

I asked the LLM if it could provide me a list of tools, technologies, and platforms used for documenting software, ordered from a less "docs-as-code" approach to a more documentation-based approach were docs are seen as product. I also noted that this list should also represent the level of technological autonomy provided by each tool - from less to more autonomous.

The output left me really astonished, in the sense that's perfectly accurate and spot on:

#TechnicalWriting #DocsAsCode #TechnicalDocumentation #SoftwareDocumentation #SoftwareDevelopment #TechnicalCommunication

Docs as Code: Наш опыт документирования с LaTeX и Dev container

В мире разработки мы постоянно сталкиваемся с технической документацией — она повсюду, от спецификаций API до архитектурных решений. И мы хотим, чтобы документация была структурированной, актуальной и удобной… но в реальности чаще имеем дело с хаотичным набором разрозненных материалов, которые теряются между Confluence, почтой и Google Docs, стремительно устаревают и выглядят небрежно, с «плывущими» таблицами и запутанной структурой. Представили этот беспорядок? Хорошая новость: есть способ автоматизировать и стандартизировать документацию, сделав её такой же управляемой, как код — через модель docs as code . В статье вместе вспомним базовые принципы этого подхода, расскажем про наш опыт документирования и поделимся репозиторием с готовым шаблоном LaTeX для максимально быстрого старта без установки зависимостей!

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

#Документация #latex_шаблон #docsascode #devcontainer #автоматизация_документации #devcontainer_для_latex #cicd_для_pdf #latex_для_начинающих

“The goal from starting out is to be able to create an API documentation suite from scratch. The minimal viable document, or the minimum the document must contain before it’s released, includes having all the calls covered, a description, even if only one sentence at this point, for every field and call, section overviews, call examples, and examples of each field. I suggest also creating a Postman collection file for each API suite. A Postman collection file is a complete set of all the requests and that each request may be run by clicking it; it’s a convenience to clients.

Being able to create that document indicates the writer’s proficiency in the mechanics of API documentation. There is a sense of accomplishment when achieving this and comfort with this process. And rightly so. They have the privilege now of calling themselves API documentation writers.”

https://robertdelwood.medium.com/starting-api-documentation-writers-obstacles-to-watch-out-for-e0907610466f

#TechnicalWriting #APIDocumentation #APIs #Programming #OpenAPI #DocsAsCode #SoftwareDevelopment #Postman

How Docs-as-Code Helped #Pinterest Improve #Documentation Quality

https://www.infoq.com/news/2025/06/docs-as-code-at-pinterest/

#DocsAsCode

Over the past few years, #Pinterest has been embracing #DocsAsCode across the organization.

The outcome?
✅ Improved documentation quality
✅ Higher team satisfaction
✅ A transformed culture of collaboration, quality control, and discoverability

Learn more: https://bit.ly/45nCZiZ

#InfoQ #SoftwareArchitecture

"Most guides to docs like code, even the ones for non-devs, assume you have some developer knowledge: maybe you're already using version control, or you've encountered build pipelines before, or you're working alongside developers.

This guide is for the people who read that paragraph and wished it came with a glossary. This is docs like code for people who don't know what git is and have never installed VS Code.

This post explains terminology and concepts, to help you get a mental model of what's going on. If you prefer to dive in and pick up concepts as you go, skip straight to the tips in How to learn, and come back to the conceptual info as needed."

https://deborahwrites.com/blog/docs-like-code-basic-intro/

#TechnicalWriting #SoftwareDocumentation #SoftwareDevelopment #Programming #DocsAsCode #Git #Markdown #TechnicalCommunication #MkDocs #VSCode

Текст без опечаток в документации и не только: внедряем CSpell

В статье приведен обзор возможностей спеллчекера CSpell, а также проанализированы сложности, с которыми я столкнулся при адаптации этого инструмента для работы с нашей документацией в парадигме Docs as Code. Статья будет полезна всем, кто хочет научиться проверять тексты в файлах любых форматов, будь то Markdown, YAML или комментарии в коде. Больше всего пользы из нее вынесут технические писатели и те, кто формирует процессы, связанные с документацией. Помимо работы в командной строке, в статье рассматриваются примеры прекоммитных проверок и интеграции с VS Code.

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

#документация #спеллчекер #орфография #docsascode #cspell #текст

"The following are my suggestions regarding what else to consider for each of Daryl White’s excellent questions about choosing a toolset for documenting a software product or project.

I have appended a brief guide to the main/broad categories of documentation toolsets and some of the platforms/components that are popular in each.

Finally, this resource ends with a table of possible solutions for various scenarios you might find yourself in.

Before we start with the existing list of questions, I want to highlight one that I think is most important of all, but which is often assumed by people who create these kinds of guides, as they tend to come from one or another world already.

What are you documenting?

When it comes to software technical writing, the more appropriate way to ask this might be: For what user roles is your documentation intended?

For graphical end-user interfaces (GUIs), the largest range of docs tooling is available, but here some of the more commercial turnkey tools have most of their advantages.

For administrator interfaces (installation, configuration, etc), again any tooling will work, but we start seeing real advantages for lightweight markup, codebase integration, and version control.

For developer interfaces, docs-as-code offers significant advantages. Developers can better contribute directly, and it’s generally friendlier for coded samples. APIs (native and remote), SDKs, and CLIs are almost certainly best documented in a docs-as-code environment, even if you integrate it with a more conventional platform for end-user docs."

https://gist.github.com/briandominick/d4cbe11228de0ebe31cda630976af4ef

#TechnicalWriting #SoftwareDocumentation #Documentation #DocsAsCode #TechnicalCommunication #InformationArchitecture #CCMS

"The accompanying diagram is intended to help you quickly decide how to document an API, but particularly a REST API. The first split is just to make sure you are looking for the right kind of API.

Here is some more context to help you decide on an approach and get started."

https://gist.github.com/briandominick/3ffab6be460fbde799aa34e0a42a4299

#API #APIs #APIDesign #REST #APIDocumentation #OpenAPI #DocsAsCode #TechnicalWriting #TechnicalCommunication

“A README acts as the front door to an API, offering consumers brief and sufficient information to get started. A full documentation is a place where consumers go to when they need to find information about any detail of the API. Having one doesn't mean you shouldn't have the other. But, having a README is, in my opinion, the very minimum you can do if you're serious about your API. And, at the very minimum, there are three elements I'd consider.”

#APIs #APIDocumentation #Markdown #TechnicalWriting #Git #DocsAsCode

https://apichangelog.substack.com/p/three-elements-of-a-good-api-readme

"The good news is that the job market is going to recover as those owners of code progressively realize the limitations that are inherent to replacing the folks at the periphery with numb language models, something they’re already noticing when it comes to coding tasks. After a stint of degrowth that has felt way too long, companies will seek to grow again in a more sustainable fashion, a trend that will carry the need for better documentation with it.

The catch is that life in the periphery of tech will require AI augmentation and training. If past job offers emphasized API documentation and coding skills, in 2025 tech writers will have to be proficient operators of AI tools, both for writing in docs-as-code environments as for becoming coding associates, able to execute docs infrastructure and toolchain work. When done well, job interviews will ask writers to be able to use AI in writing tests in efficient, innovative ways.

If I’ve learned something this year is that the LLM-powered writing and coding isn’t going away. Technical writers will need to focus more on content strategy, information architecture, and tooling, and less on writing; at the same time, they’ll be expected to know how to use tools like Cursor’s composer mode to set up entire documentation sets in little time, and then iterate. As I explained in What’s a docs engineer, writers will continue specializing in two separate strains."

https://passo.uno/tech-writing-predictions-2025/

#TechnicalWriting #TechnicalWriters #LLMs #AI #GenerativeAI #DocsAsCode

"Asking me what’s my favourite documentation is a bit like asking me what are the best doorways I’ve crossed in my life. We remember places, not open doors; we recall the things we did through software, not great docs. In my case, I seldom remember good or great documentation because its purpose is not to get in the way. On the other hand, I do remember lots of bad documentation when it failed to provide answers. The curse of technical writing is that the best expressions of our work are the ones people rarely notice, because they offer so little friction they never disturb the user’s flow.

There are exceptions to this, of course. The first is documentation that is presented in such a way that it generates a “Wow” moment. Perhaps it’s a code snippet you can run, an interactive demo, or similar gimmicks. While they’re not key to great documentation, they make for some memorable experiences, though that can backfire quickly if the docs aren’t good. The other exception are docs that teach us something new, either through conceptual explanations or examples. Some of the best docs I’ve read are aware that they’re also teaching new ideas and concepts. You can tell because they grin."

https://passo.uno/my-favorite-tech-docs/

#TechnicalWriting #SoftwareDocumentation #Docs #DocsAsCode #SoftwareDevelopment

"In short, APIs are how businesses speak to one another. Breaking this oath with a poor integration experience is a surefire way to reduce your business potential. By utilizing a source of truth and baking a specification-first approach into your API development and documentation practices, you more clearly communicate changes, reducing the possibility of broken clients and promoting forward compatibility. Great API products must be well-described, easy to understand, and predictable in the long run.

In the end, the business effects of specification-driven development are manifold. Whether you're building RESTful, GraphQL, or event-driven partner services, having reliable API documentation is important to compete in the digital economy. This consistency equates to a better partner experience, leading to stickier partners and less customer churn. By enabling smoother integrations and reducing frustration, spec-first documentation directly contributes to partner retention and loyalty, which ultimately drives revenue growth."

https://bump.sh/blog/how-spec-first-api-documentation-aids-partner-integration

#APIs #APIDocumentation #TechnicalWriting #SpecFirst #SoftwareDocumentation #Docs #DeveloperExperience #DocsAsCode

Pleased to say that I've had a tutorial proposal accepted on how to integrate the Vale Text Linter into your Docs-As-Code technical writing project.

"Upgrade your Docs-As-Code Foo with the Vale Text Linter"

Hope to see you in Adelaide in January for a beer or two... 🍺

https://2025.everythingopen.au/

#ValeLint #DocsAsCode #DocsLikeCode

https://vale.sh/

Gitlab и Specification-as-Code: Спасение от хаоса и кофеиновой зависимости

Для компании SimpleOne управление спецификациями требований было настоящей головной болью, требующей унификации подходов и учета потребностей разных команд. Мы стояли перед выбором: сделать свое решение для управления требованиями и сбора спецификаций или попробовать уже существующие практики. Концепция DocOps привлекла внимание тем, что помогает стандартизировать инструменты и навести порядок в хранении артефактов. В этой статье мы расскажем, как внедрили подход на основе docs as code, какие преимущества получили и какие трудности преодолели на пути.

https://habr.com/ru/companies/simpleone/articles/844080/

#аналитика #спецификация #управление_проектами #управление_требованиями #системный_анализ #бизнес_анализ #docsascode #git #markdown #docs_as_code

Gitlab и Specification-as-Code: Спасение от хаоса и кофеиновой зависимости

Для компании SimpleOne управление спецификациями требований было настоящей головной болью, требующей унификации подходов и учета потребностей разных команд. Мы стояли перед выбором: сделать свое решение для управления требованиями и сбора спецификаций или попробовать уже существующие практики. Концепция DocOps привлекла внимание тем, что помогает стандартизировать инструменты и навести порядок в хранении артефактов. В этой статье мы расскажем, как внедрили подход на основе docs as code, какие преимущества получили и какие трудности преодолели на пути.

https://habr.com/ru/companies/simpleone/articles/844080/

#аналитика #спецификация #управление_проектами #управление_требованиями #системный_анализ #бизнес_анализ #docsascode #git #markdown #docs_as_code

Gitlab и Specification-as-Code: Спасение от хаоса и кофеиновой зависимости

Для компании SimpleOne управление спецификациями требований было настоящей головной болью, требующей унификации подходов и учета потребностей разных команд. Мы стояли перед выбором: сделать свое решение для управления требованиями и сбора спецификаций или попробовать уже существующие практики. Концепция DocOps привлекла внимание тем, что помогает стандартизировать инструменты и навести порядок в хранении артефактов. В этой статье мы расскажем, как внедрили подход на основе docs as code, какие преимущества получили и какие трудности преодолели на пути.

https://habr.com/ru/companies/simpleone/articles/844080/

#аналитика #спецификация #управление_проектами #управление_требованиями #системный_анализ #бизнес_анализ #docsascode #git #markdown #docs_as_code

if anyone has been to my various Docs As Code talks, I've moved the repo to https://gitlab.com/alecthegeek/docs-as-code (because I changed employer).

#docsascode #docslikecode

Docs-as-Code, Accessibility, OWASP Top Ten – wir haben neue Trainings im Programm! Ist etwas für dich dabei? https://www.socreatory.com/de/news/neue-trainings-2023?ref=mastodon #trainings #softwarearchitektur #docsascode #documention #owasp #websecurity #accessibility

Many Thanks to the #Codeberg Team for reviewing my pull requests and merging my contributions into their official repository:

1. Pushing output from #SSGs into Codeberg Pages
https://tinyurl.com/yckmpcvx

2. #DocsAsCode with #sphinx
https://tinyurl.com/mwwk4vmk :opensource: :codeberg: