#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

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

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

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

"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

“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

"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

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/

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

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:

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: