Lmst

“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

Fallbeispiel SeaLion: Satellitenentwicklung mit Docs-as-Code
Das SeaLion-Projekt entwickelte einen CubeSat mit Docs-as-Code: Artefakte werden in gitHub in YAML-Notation festgehalten.
https://www.se-trends.de/sealion-sysml-v2-docs-as-code/
#Fallbeispiel #LuftRaumfahrt #ModellierungMBSE #OpenSource #Werkzeuge #DocsasCode #M30ML #SeaLion #YAML

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

개발자는 코드를 리뷰하는데, 왜 문서는 그냥 쓰고 넘기나요?

Pinterest는 문서도 코드처럼 다루는 시스템 PDocs를 도입했습니다.

좋은 문서는 좋은 도구에서 시작됩니다.
PDocs는 단순한 기술 구현이 아니라 “문서를 신뢰할 수 있게 만드는 개발 문화”를 디자인한 프로젝트입니다.

#DocsAsCode #PDocs #기술문서 #개발도구
https://news.mrlatte.net/posts/2025/06/09/pdocs-pinterest-docs-as-code

I’m a big fan of docs-as-code for more or less any type of content publishing, but I’m less of a fan of Jekyll, the default tool used in GitHub pages. I also prefer ReStructuredText over Markdown as a markup format, so Sphinx is definitely on my shortlist of SSGs (Static Site Generators) for my projects. I recently switched the rst2pdf docs over to using Sphinx hosted on GitHub pages, so here are my setup notes. […]

https://lornajane.net/posts/2025/publish-to-github-pages-with-sphinx

🛠️ Diagramm oder Doku? Warum nicht beides!

Unser CEO @madmas zeigt am 12. Mai auf der betterCode() ArchDoc, wie Architekturdiagramme und Dokumentation gemeinsam entstehen – mit PlantUML, AsciiDoc & Antora, automatisiert via GitLab CI.
Ideal für alle, die Architektur dokumentieren, ohne doppelte Arbeit zu machen. Oder Chaos. 😉
🔗 https://archdoc.bettercode.eu/veranstaltung-83492-se-0-diagramm-oder-doku-warum-nicht-beides.html

#DocsAsCode #SoftwareArchitecture #PlantUML #AsciiDoc #Antora

"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

Writeup of some great recent customer conversations, experiences and recommendations on the work blog: [https://redocly.com/blog/docs-as-code-pragmatism}(https://redocly.com/blog/docs-as-code-pragmatism)

https://lornajane.net/resource/docs-as-code-tech-writer-productivity-hack

One of the most-asked questions for our docs-as-code platform where writers or their teams might be new to git: [https://redocly.com/blog/git-branching-for-docs](https://redocly.com/blog/git-branching-for-docs)

https://lornajane.net/resource/git-branching-strategies-for-docs-projects

"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