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

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

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

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

"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

"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

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

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

"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

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/

Where's the lie
#DITA #markdown #techwriting #docsascode

#TechnicalWriting #SoftwareDocumentation #SoftwareDevelopment #DocsAsCode: "While writing documentation is the most obvious part of a Technical Writer’s job, it’s actually the element you will probably spend the least amount of time on in your day-to-day work. “I write maybe a quarter of my time,” says Mike. The rest of the day is made up of activities like:

- Setting up and testing software
- Figuring out the process and schedule for releasing a new feature
- Identifying and submitting bug reports

Technical Writers typically write about brand new features that haven’t been documented or released yet, Mike says.

Experimenting in this early stage naturally leads to finding bugs and collaborating with development to determine workarounds. While filing bugs sounds like a diversion, Mike says it’s actually a big part of what makes the role rewarding. “When I finally get to the solution, I think, ‘Wow, this actually works! I can’t wait to write about this.’”"

https://www.codecademy.com/resources/blog/what-does-a-technical-writer-do/

IT'S HERE! The PR Focus public beta is finally open. If you:

- Are a #developer who makes or reviews PRs, or is assigned work in GitHub
- Are a #DocsAsCode technical writer who makes or reviews PRs, or is assigned work in GitHub
- Are a #TechnicalWriter, team lead, project manager, or work at an agency or consulting firm where you need to keep track of PRs across repos as the source of truth for your work

PR Focus might be helpful to you!

Join the TestFlight here: https://testflight.apple.com/join/PmdjrF6U

Pretty good list of advices!

#TechnicalWriting #SoftwareDocumentation #Documentation #DocsAsCode #AI: “If you’re shipping a product and that product is more difficult to use than a kazoo, you need the product to communicate to users through UX writing, docs, or both. That’s what the technical writer in your team can accomplish, or at least spearhead. It’s not about unique talent: it’s about watering the plant of specialization.

Picture yourself strolling through the aisles of a technical writing Costco, your huge shopping cart ready to transport the resources you need for your technical writer to succeed. Your list would contain the following:

- Provide the writer with adequate access level
- Mind the technical documentation toolchain
- Work with your writer toward a docs-first approach
- Put your writer at the center of AI development
- Empower your tech writer to tear down content silos”

https://passo.uno/how-to-tech-writer-success/

Как мы пытались в Docs as code и проиграли

Что такое Docs as Code классно описано в статье Docs as Code: введение в предмет . В двух словах: это ведение документации на языке разметки (Markdown, AsciiDoc) с хранением в репозитории. Плюшки — все вытекающие от работы с репозиторием. Минусы — в этой статье. На осенних Analyst Days прошлого года добрая четверть докладов была посвящена теме Docs as Code. На тот момент конклав аналитиков на моём прежнем месте работы уже 9 месяцев решал, нужен ли на проекте модный-стильный-молодёжный Docs as Code или всё же остаться в дышащем на ладан Confluence. К чему пришли — не знаю. На новом месте работы мы внедрили Docs as Code за неделю — было чёткое понимание проблематики, подход казался выигрышным решением. Используем полгода.

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

#TechnicalWriting #DocsAsCode #Markdown #Git #SoftwareDocumentation #GitWorkflows #SoftwareDevelopment: "When you use a docs as code workflow, you need to codify your docs processes and instantiate them in your Git workflow. So you not only need to define the following:

- When to publish doc updates
- How to release doc updates
- How to coordinate a docs release with a product release

You also need to define Git best practices for your team about how to manage those, such as:

- Whether to use release branches, or merge pull requests frequently but publishing infrequently.
- Whether to use Git rebase or Git merge to maintain Git history in a given branch.
- Whether and how to use feature branches and pull requests.
- Whether to squash merge pull requests to main.

Even if you manage to define best practices that your team is committed to following, there isn’t a way to force your documentation contributors to adhere to all of these best practices. Due to the lack of enforcement of these best practices, you can easily end up in a situation where writers follow slightly different practices based on what their tools make easy to do."

https://thisisimportant.net/posts/docs-as-code-broken-promise/

The #writethedocs community has been discussing #docsascode a lot the past few days, and it pushed me to finally finish and publish a post I've been noodling on for months... docs as code is a broken promise

https://thisisimportant.net/posts/docs-as-code-broken-promise/

Der Ansatz Docs-as-Code hilft euch und eurem Team die Architekturdokumentation einfacher zu pflegen.

Erfahrt mehr in unserem Training "Docs-as-Code" mit @sippsack und @rdmueller vom 04. bis 05. März 2024, online:

https://www.socreatory.com/de/trainings/docascode/events/15efbf05ba75?ref=mastodon070224

#SoftwareDocumentation #DocsAsTests #DocsAsCode #APIDocumentation #TechnicalWriting #SoftwareTesting #SoftwareDevelopment: "I initially developed and implemented Docs as Tests at Skyflow, a startup that moves fast and releases features and updates even faster than I’d experienced before. I searched for tools to help me manage the pace of changes: there were style linters, API testers, and engineering-focused testing tools, but there wasn’t anything to easily help me validate the product descriptions or procedures in my docs. So I built my own, and Doc Detective was born. Doc Detective is a toolkit that parses docs and runs tests (like stepping through procedures) directly against UIs and APIs. It’s designed so non-engineers can use it individually, but teams can also collaborate. When I set it up to test my docs, it caught issues that I had no idea of. It was a game-changer.

But Doc Detective is just a tool (a good one, I like to think!), and no tool solves every problem. I wanted to find a way to apply my learnings to the broader docs community, and I came up with Docs as Tests—a strategy that can be implemented with whichever tools you choose to validate your docs. I’m excited to share my learnings with you and to learn from you as well."

https://www.docsastests.com/docs-as-tests/concept/2024/01/09/intro-docs-as-tests.html

Can I use #AI and #LLMs in a #docsascode pipelines? Definitely yes - find out how, and discuss approaches on Jan 24 in our online meetup!

https://www.meetup.com/continuous-documentation-regulars/events/298145885/