#technicalwriting — Public Fediverse posts

Just released. Judging from its Table of Contents, it promises to be very interesting in mere historical and technical terms. My suspiction is that it runs the danger of being too much enciclopedic.

From Markup to Markdown: The Evolution of Technical Writing, Typesetting Tools and Frameworks

Jim Hall (Apress)

“From Markup to Markdown is a history of how writers have used computers to write, and a look ahead to see what the future looks like for technical writing. This book explores both “technology history” and “how it works” about how we write with computers, with code examples so readers can explore and fully understand how each writing tool and framework works behind the scenes.

Starting with an overview of the major milestones of writing with digital technologies since the 1960s, you will learn about RUNOFF and how this inspired roff on Unix (and the more familiar versions, nroff and troff). You will also explore word processing milestones like WordStar, and printing technologies like the phototypesetter and the dot matrix printer, before moving onto modern markup and writing systems like HTML, Markdown and DITA and how they play a role in how we write today.

From Markup to Markdown is ideal for writers, technical communication professionals, history of computing researchers as well as “retro-computing” enthusiasts.

You Will Learn to:

- Explore the history of technical writing in the age of the personal computer, from the 1960s to the present day
- Understand how the technologies and tools have evolved over time
- Learn how each tool works with simple and clear code samples and exercises, giving you an under-the-hood understanding of how each system works, from RUNOFF markup to modern Markdown

This Book is For:
- Technical writers, technology history enthusiasts and researchers.”

https://books.google.pt/books?id=2XsAEgAAQBAJ

#TechnicalWriting #Markup #HTML #Markdown #DITA #TechnicalCommunication #HistoryOfTechnology

Just released. Judging from its Table of Contents, it promises to be very interesting in mere historical and technical terms. My suspiction is that it runs the danger of being too much enciclopedic.

From Markup to Markdown: The Evolution of Technical Writing, Typesetting Tools and Frameworks

Jim Hall (Apress)

“From Markup to Markdown is a history of how writers have used computers to write, and a look ahead to see what the future looks like for technical writing. This book explores both “technology history” and “how it works” about how we write with computers, with code examples so readers can explore and fully understand how each writing tool and framework works behind the scenes.

Starting with an overview of the major milestones of writing with digital technologies since the 1960s, you will learn about RUNOFF and how this inspired roff on Unix (and the more familiar versions, nroff and troff). You will also explore word processing milestones like WordStar, and printing technologies like the phototypesetter and the dot matrix printer, before moving onto modern markup and writing systems like HTML, Markdown and DITA and how they play a role in how we write today.

From Markup to Markdown is ideal for writers, technical communication professionals, history of computing researchers as well as “retro-computing” enthusiasts.

You Will Learn to:

- Explore the history of technical writing in the age of the personal computer, from the 1960s to the present day
- Understand how the technologies and tools have evolved over time
- Learn how each tool works with simple and clear code samples and exercises, giving you an under-the-hood understanding of how each system works, from RUNOFF markup to modern Markdown

This Book is For:
- Technical writers, technology history enthusiasts and researchers.”

https://books.google.pt/books?id=2XsAEgAAQBAJ

#TechnicalWriting #Markup #HTML #Markdown #DITA #TechnicalCommunication #HistoryOfTechnology

I like the prose linter Vale, because it helps me stay closer in compliance with our documentation style guide.

A bug with handling restructuredtext disturbed my work since yesterday.

On systems using pyenv and having imagemagick installed, each Vale run of rst2html triggers the screenshot tool from imagemagick, because Bash instead of Python interprets `import sys`. It blocks my keyboard input until I click once.

See
https://github.com/vale-cli/vale/issues/1137

#technicalwriting #vale #restructuredtext

As an author, you sometimes rework an explanation several times before it feels right. That happened to me with a section on how mathematical operators and functions are implemented in Java, which I needed for my current book on the Java Vector API. I have published the section here in case others find it useful: https://www.tutego.de/blog/javainsel/2026/08/what-actually-runs-when-you-call-math-sin-java-source-fdlibm-and-what-hotspot-does-instead/
#java #compiler #floatingpoint #technicalwriting

As an author, you sometimes rework an explanation several times before it feels right. That happened to me with a section on how mathematical operators and functions are implemented in Java, which I needed for my current book on the Java Vector API. I have published the section here in case others find it useful: https://www.tutego.de/blog/javainsel/2026/08/what-actually-runs-when-you-call-math-sin-java-source-fdlibm-and-what-hotspot-does-instead/
#java #compiler #floatingpoint #technicalwriting

"Consider this idea: A company has 100 tech-writer-specific skills that are highly adopted and used across the organization. This collection of skills, focusing on internal authoring skills, has skills for doing virtually anything related to tech writing that you can imagine — fixing a bug, applying a style edit, checking release notes for accuracy, fixing comments in proto styles, and more. The skills don’t do the job entirely themselves but rather act as power tools for the writers, accelerating and amplifying their work.

Not everyone uses all 100 of the tech writer skills. Instead, each tech writer registers the skills most relevant to their tasks in their agent’s configuration. Some have even created virtual agents that have these skills.

Is this 100 TW skills idea worthwhile? The merits of the 100 skills idea are questionable; there are many problems associated with it — skills are hard to share because tech writing processes are idiosyncratic, monolithic skills that try to do too much get rejected, and there’s a fundamental trust problem when running someone else’s skill on your content. And yet, I think the idea could be interesting. We would essentially be externalizing the skills of an entire profession in a way that could be used cross-organizationally, by any role. This is unsettling as it may lead to our irrelevance. But there’s also a high possibility of amplification: by externalizing our skills, we build upon each others’ strengths. Is it possible to construct skills in such a way that other writers, particularly those who didn’t make the skills, find them useful?

In this series, I’ll build out these ideas into a course on skills."

https://idratherbewriting.com/ai/skills.html

#TechnicalWriting #SoftwareDocumentation #AI #AIAgents #GenerativeAI #LLMs #AgenticAI #AgentSkills

"Consider this idea: A company has 100 tech-writer-specific skills that are highly adopted and used across the organization. This collection of skills, focusing on internal authoring skills, has skills for doing virtually anything related to tech writing that you can imagine — fixing a bug, applying a style edit, checking release notes for accuracy, fixing comments in proto styles, and more. The skills don’t do the job entirely themselves but rather act as power tools for the writers, accelerating and amplifying their work.

Not everyone uses all 100 of the tech writer skills. Instead, each tech writer registers the skills most relevant to their tasks in their agent’s configuration. Some have even created virtual agents that have these skills.

Is this 100 TW skills idea worthwhile? The merits of the 100 skills idea are questionable; there are many problems associated with it — skills are hard to share because tech writing processes are idiosyncratic, monolithic skills that try to do too much get rejected, and there’s a fundamental trust problem when running someone else’s skill on your content. And yet, I think the idea could be interesting. We would essentially be externalizing the skills of an entire profession in a way that could be used cross-organizationally, by any role. This is unsettling as it may lead to our irrelevance. But there’s also a high possibility of amplification: by externalizing our skills, we build upon each others’ strengths. Is it possible to construct skills in such a way that other writers, particularly those who didn’t make the skills, find them useful?

In this series, I’ll build out these ideas into a course on skills."

https://idratherbewriting.com/ai/skills.html

#TechnicalWriting #SoftwareDocumentation #AI #AIAgents #GenerativeAI #LLMs #AgenticAI #AgentSkills

"In this podcast, co-host Fabrizio Ferri-Benedetti and I chat with Sarah Deaton, a technical writer at Anthropic who works on the Claude Code docs, about what documentation work looks like when much of it is automated. We discuss orchestrating docs through skills and agents rather than writing them, mining AI assistant conversations for doc gaps, running forensics on every false claim that reaches the docs, new metrics like time-to-correction and steers per PR, the fences that keep AI-generated docs honest, and how she closed more than a hundred pull requests in a single day."

https://idratherbewriting.com/blog/podcast-deaton-anthropic-tw-automation

#TechnicalWriting #SoftwareDocumentation #Automation #DocsOrchestration #Anthropic #ClaudeCode #AIAgents #AgenticAI

"In this podcast, co-host Fabrizio Ferri-Benedetti and I chat with Sarah Deaton, a technical writer at Anthropic who works on the Claude Code docs, about what documentation work looks like when much of it is automated. We discuss orchestrating docs through skills and agents rather than writing them, mining AI assistant conversations for doc gaps, running forensics on every false claim that reaches the docs, new metrics like time-to-correction and steers per PR, the fences that keep AI-generated docs honest, and how she closed more than a hundred pull requests in a single day."

https://idratherbewriting.com/blog/podcast-deaton-anthropic-tw-automation

#TechnicalWriting #SoftwareDocumentation #Automation #DocsOrchestration #Anthropic #ClaudeCode #AIAgents #AgenticAI

““The biggest challenge is documentation being out of sync with the API that’s available,” says Sundaresan. “Docs being out of sync is actually a worse problem today since we release much faster.”

While working at Microsoft, he found some Azure command-line interfaces (CLIs) had more than 1,500 commands. CLIs and APIs change with new versions, and new parameters are often added without updating the corresponding documentation. To his point, a 2024 APIContext study found that 75% of production APIs don’t match their specification files. This mismatch can break integrations and applications.

Knowledge decay also creates substantial rework. “The challenge is everywhere,” says Sundaresan.

“Back when I worked at eBay, engineers would get moved around all the time,” he says. Much of the work relied on consultants, who would move on to the next job once a project was complete. This led to substantial duplication, as later developers would struggle to understand the original code and decide to redo it or change large portions of it.

He estimates that only 15% to 20% of code is newly written, while 60% to 65% involves modernization, migration, and maintenance. Whether it’s out of sync documentation or opaque code bases, that one missing link can result in significant wasted effort. “You can get 99% right, but then the 1% that you get wrong can appear as a huge time sink.””

https://leaddev.com/ai/how-to-avoid-knowledge-decay-in-software-engineering

#TechnicalDebt #SoftwareEngineering #Documentation #TechnicalWriting #SoftwareDevelopment #AI #LLMs

““The biggest challenge is documentation being out of sync with the API that’s available,” says Sundaresan. “Docs being out of sync is actually a worse problem today since we release much faster.”

While working at Microsoft, he found some Azure command-line interfaces (CLIs) had more than 1,500 commands. CLIs and APIs change with new versions, and new parameters are often added without updating the corresponding documentation. To his point, a 2024 APIContext study found that 75% of production APIs don’t match their specification files. This mismatch can break integrations and applications.

Knowledge decay also creates substantial rework. “The challenge is everywhere,” says Sundaresan.

“Back when I worked at eBay, engineers would get moved around all the time,” he says. Much of the work relied on consultants, who would move on to the next job once a project was complete. This led to substantial duplication, as later developers would struggle to understand the original code and decide to redo it or change large portions of it.

He estimates that only 15% to 20% of code is newly written, while 60% to 65% involves modernization, migration, and maintenance. Whether it’s out of sync documentation or opaque code bases, that one missing link can result in significant wasted effort. “You can get 99% right, but then the 1% that you get wrong can appear as a huge time sink.””

https://leaddev.com/ai/how-to-avoid-knowledge-decay-in-software-engineering

#TechnicalDebt #SoftwareEngineering #Documentation #TechnicalWriting #SoftwareDevelopment #AI #LLMs

I somewhat agree, but I'm still a sucker for non-fiction books. If a book is really good, it can provide you not just the required context and some knowledge of a given field, but also leave you with a few words of wisdom that can inspire you.

Also, I recommend everyone to follow what's cooking in /r/singularity

"Books and courses are traditional ways of learning. For senior tech writers, traditional learning won’t do. We’re living in the middle of a small technological revolution: new AI models, tools, and theories surface every week. Buying a book about anything that isn’t timeless theory or an established classic is now like buying an old newspaper: useful mainly as a historical record. Instead, stay abreast of tech news, because that’s the only thing that provides a return.

Staying up-to-date is not limited to reading Hacker News or Simon Willison’s blog: there’s also a very important social aspect to it. Join meetups in your area and enter Slack or Discord communities to replace the watercooler convos you had at work. Absorb trends, podcasts, worries, and jargon. It’s like moving to a new country: exhausting, but also exciting. In my case, I follow threads in several Slack communities where I can get a first-hand feeling of what’s cooking.

There are exceptions, of course. Books like the one CT Smith is writing, which focuses on how to sell technical writing to startup founders, are the right kind of material for this age. I, too, think that software is becoming marketing: as software becomes abundant, coding skills matter less than reputation and positioning. Docs are a service, not a deliverable: learn how to make the case for it. If you’re not a beginner, the only kind of books worth reading are the ones that teach you how to think and sell, not how to do the actual work. You already know the craft."

https://passo.uno/job-hunt-tech-writers-ai/

#TechnicalWriting #Documentation #AI #SoftwareDocumentation #ContentEngineering #SoftwareDevelopment

I somewhat agree, but I'm still a sucker for non-fiction books. If a book is really good, it can provide you not just the required context and some knowledge of a given field, but also leave you with a few words of wisdom that can inspire you.

Also, I recommend everyone to follow what's cooking in /r/singularity

"Books and courses are traditional ways of learning. For senior tech writers, traditional learning won’t do. We’re living in the middle of a small technological revolution: new AI models, tools, and theories surface every week. Buying a book about anything that isn’t timeless theory or an established classic is now like buying an old newspaper: useful mainly as a historical record. Instead, stay abreast of tech news, because that’s the only thing that provides a return.

Staying up-to-date is not limited to reading Hacker News or Simon Willison’s blog: there’s also a very important social aspect to it. Join meetups in your area and enter Slack or Discord communities to replace the watercooler convos you had at work. Absorb trends, podcasts, worries, and jargon. It’s like moving to a new country: exhausting, but also exciting. In my case, I follow threads in several Slack communities where I can get a first-hand feeling of what’s cooking.

There are exceptions, of course. Books like the one CT Smith is writing, which focuses on how to sell technical writing to startup founders, are the right kind of material for this age. I, too, think that software is becoming marketing: as software becomes abundant, coding skills matter less than reputation and positioning. Docs are a service, not a deliverable: learn how to make the case for it. If you’re not a beginner, the only kind of books worth reading are the ones that teach you how to think and sell, not how to do the actual work. You already know the craft."

https://passo.uno/job-hunt-tech-writers-ai/

#TechnicalWriting #Documentation #AI #SoftwareDocumentation #ContentEngineering #SoftwareDevelopment

Technical writing has evolved significantly. In the past, the focus was on creating documentation to save developers time so they could concentrate on coding. Nowadays, technical writers not only save developers time but also tokens so their quota is used for coding rather than documenting.

#TechnicalWriting #AI #Efficiency

Technical writing has evolved significantly. In the past, the focus was on creating documentation to save developers time so they could concentrate on coding. Nowadays, technical writers not only save developers time but also tokens so their quota is used for coding rather than documenting.

#TechnicalWriting #AI #Efficiency

"The comparison with Asimov’s robots and Banks’s Minds only goes so far. Their language rests on shared experience and a shared model of the world. The register in this experiment was generated externally from a source document and tested against a particular task. Good old garbage in, garbage out still applies: remove too much information and answers go banana.

Rewrites are an editorial, human choice. They belong to the same class of decisions a writer makes when selecting what goes in a quickstart and what gets left for the reference. This is also the case made by approaches such as SCOPE and Telegraph English: deleting tokens tends to cut the connective tissue between facts, so rewriting each passage fares better than deleting stuff.

So, my answer is yes: you can compile human writing to some dialect of LLMese, but only if you really need to save tokens, and only if you have ways of ensuring that meaning isn’t lost. If it makes sense in your pipeline, you might as well give it a go."

https://passo.uno/write-docs-llms-language/

#TechnicalWriting #AI #LLMs #Tokenomics #Chatbots #Language

"The comparison with Asimov’s robots and Banks’s Minds only goes so far. Their language rests on shared experience and a shared model of the world. The register in this experiment was generated externally from a source document and tested against a particular task. Good old garbage in, garbage out still applies: remove too much information and answers go banana.

Rewrites are an editorial, human choice. They belong to the same class of decisions a writer makes when selecting what goes in a quickstart and what gets left for the reference. This is also the case made by approaches such as SCOPE and Telegraph English: deleting tokens tends to cut the connective tissue between facts, so rewriting each passage fares better than deleting stuff.

So, my answer is yes: you can compile human writing to some dialect of LLMese, but only if you really need to save tokens, and only if you have ways of ensuring that meaning isn’t lost. If it makes sense in your pipeline, you might as well give it a go."

https://passo.uno/write-docs-llms-language/

#TechnicalWriting #AI #LLMs #Tokenomics #Chatbots #Language

I did an interview with Technically We Write about working on the #LibreOffice user guides and creating documents with LibreOffice #Writer
#Foss #Floss #TechnicalWriting #TheDocumentFoundation

https://technicallywewrite.com/2026/07/13/interview

I did an interview with Technically We Write about working on the #LibreOffice user guides and creating documents with LibreOffice #Writer
#Foss #Floss #TechnicalWriting #TheDocumentFoundation

https://technicallywewrite.com/2026/07/13/interview

510 daily posts on The Main Thread taught me two things: consistency works, and agents only help when verification keeps up.

I am changing the cadence now. Still Quarkus, Java, standards, and agentic engineering. More room for tests, examples, and claims that earned their confidence.

https://www.the-main-thread.com/p/510-posts-later

#Quarkus #Java #AIAgents #TechnicalWriting

510 daily posts on The Main Thread taught me two things: consistency works, and agents only help when verification keeps up.

I am changing the cadence now. Still Quarkus, Java, standards, and agentic engineering. More room for tests, examples, and claims that earned their confidence.

https://www.the-main-thread.com/p/510-posts-later

#Quarkus #Java #AIAgents #TechnicalWriting

Announcing Unified, Layered Documentation: a service to join information silos and unlock efficiency gains with consistent, high-quality documentation that adapts to its audience's goals and roles. Find out more https://www.sicpers.info/agency/, download the white paper, and book an initial, no-obligation chat! #technicalwriting #documentation #softwareengineering

Announcing Unified, Layered Documentation: a service to join information silos and unlock efficiency gains with consistent, high-quality documentation that adapts to its audience's goals and roles. Find out more https://www.sicpers.info/agency/, download the white paper, and book an initial, no-obligation chat! #technicalwriting #documentation #softwareengineering

Announcing Unified, Layered Documentation: a service to join information silos and unlock efficiency gains with consistent, high-quality documentation that adapts to its audience's goals and roles. Find out more https://www.sicpers.info/agency/, download the white paper, and book an initial, no-obligation chat! #technicalwriting #documentation #softwareengineering

The truth is that LLMs are mostly unpredictable and, as such, you can’t rely on AI agents to strictly follow the instructions stored in a markdown file. Even when they execute all the instructions contained in the skills, they often leave a backtrail full of trash/dirt. Because they’re often unruly, they need another chatbot to put them in line, as well as a human in the loop, of course. Basically, it’s a lot of trial and error…

“I acknowledge that “programming an LLM” is putting it optimistically, as skills aren’t usually deterministic scripts. But I like to think of them this way, and keep refining the skill until it yields the consistent result that I want.
Overall, I’m persuaded that tech writers who can build successful skills to automate their tasks will be on their way to the 10x tech writer goal (if that’s your aim). The best way tech writers can free up their time is by creating skills to attack those repeatable tasks (like release notes) since repeatable tasks keep chipping away at our productivity week after week. If you can fashion a skill that handles those recurring tasks, then you free up a recurring amount of bandwidth each week.

Additionally, most repeatable tasks fall into the category of mechanical toil that we want to automate with AI anyway. If we can automate the repeatable tasks, then we’ll have more time to tackle the one-off complex tasks that don’t fall into our laps weekly or biweekly.”

https://idratherbewriting.com/blog/all-about-skills-intro

#AI #LLMs #AIAgents #AgenticAI #Skills #TechnicalWriting #SoftwareDocumentation

The truth is that LLMs are mostly unpredictable and, as such, you can’t rely on AI agents to strictly follow the instructions stored in a markdown file. Even when they execute all the instructions contained in the skills, they often leave a backtrail full of trash/dirt. Because they’re often unruly, they need another chatbot to put them in line, as well as a human in the loop, of course. Basically, it’s a lot of trial and error…

“I acknowledge that “programming an LLM” is putting it optimistically, as skills aren’t usually deterministic scripts. But I like to think of them this way, and keep refining the skill until it yields the consistent result that I want.
Overall, I’m persuaded that tech writers who can build successful skills to automate their tasks will be on their way to the 10x tech writer goal (if that’s your aim). The best way tech writers can free up their time is by creating skills to attack those repeatable tasks (like release notes) since repeatable tasks keep chipping away at our productivity week after week. If you can fashion a skill that handles those recurring tasks, then you free up a recurring amount of bandwidth each week.

Additionally, most repeatable tasks fall into the category of mechanical toil that we want to automate with AI anyway. If we can automate the repeatable tasks, then we’ll have more time to tackle the one-off complex tasks that don’t fall into our laps weekly or biweekly.”

https://idratherbewriting.com/blog/all-about-skills-intro

#AI #LLMs #AIAgents #AgenticAI #Skills #TechnicalWriting #SoftwareDocumentation

Here’s why contextual and use case-based documentation matters a lot when it comes to APIs:

“The problem is that documentation is often organized entirely around individual endpoints with very little cross-endpoint guidance, implicit prerequisites, or multi-step call documentation. For this reason, API use often involves tribal knowledge held by the average human operator.

A better way to organize this, or perhaps a complementary way, is to create documentation around workflows and common scenarios. You don't have to document every single potential interaction. In many cases, simply documenting common use cases and then delineating what they share is more than enough for the agentic systems to infer how the API actually functions in practice. This, alongside additional deterministic context, will help agents understand your systems in a human-like context without having to have a human on the other side of the request.

The goal: Provide documentation not just of individual endpoints but of the collective flow between them, allowing agents to understand your service properly.”

https://nordicapis.com/10-factors-for-checking-your-apis-ai-readiness/

#API #APIs #APIDocumentation #AI #AIAgents #TechnicalWriting #SoftwareDocumentation #APIDesign

Here’s why contextual and use case-based documentation matters a lot when it comes to APIs:

“The problem is that documentation is often organized entirely around individual endpoints with very little cross-endpoint guidance, implicit prerequisites, or multi-step call documentation. For this reason, API use often involves tribal knowledge held by the average human operator.

A better way to organize this, or perhaps a complementary way, is to create documentation around workflows and common scenarios. You don't have to document every single potential interaction. In many cases, simply documenting common use cases and then delineating what they share is more than enough for the agentic systems to infer how the API actually functions in practice. This, alongside additional deterministic context, will help agents understand your systems in a human-like context without having to have a human on the other side of the request.

The goal: Provide documentation not just of individual endpoints but of the collective flow between them, allowing agents to understand your service properly.”

https://nordicapis.com/10-factors-for-checking-your-apis-ai-readiness/

#API #APIs #APIDocumentation #AI #AIAgents #TechnicalWriting #SoftwareDocumentation #APIDesign

"Now let me touch on an undiscussed aspect of skills I find interesting: skills enforce process. When I run my release documentation skill, I perform the same sequence of steps. As such, skills enforce a consistent process.

Some of the steps incorporate healthy habits into docs. For example, in my robust release docs skills, the following steps are followed:

- Analysis of source code comment tags (and any fixes)
- Analysis of logs run after the reference docs build to identify elements missing documentation.
- Analysis as to whether any changes/updates constitute breaking changes
Analysis of documentation corpus to identify needed changes across docs (and any fixes)

If I were doing these steps on my own, I might cut corners with some releases. For example, I probably wouldn’t have time to analyze the log reports or to scan all other documentation for needed updates. The skill helps me do these steps seamlessly.

Additionally, if you define a specific template for publishing, that template gets applied each time you run the skill, which also leads to more consistency."

https://idratherbewriting.com/blog/all-about-skills-intro

#AI #GenerativeAI #LLMs #Chatbots #Skills #Claude #Gemini #TechnicalWriting #SoftwareDocumentation

"Now let me touch on an undiscussed aspect of skills I find interesting: skills enforce process. When I run my release documentation skill, I perform the same sequence of steps. As such, skills enforce a consistent process.

Some of the steps incorporate healthy habits into docs. For example, in my robust release docs skills, the following steps are followed:

- Analysis of source code comment tags (and any fixes)
- Analysis of logs run after the reference docs build to identify elements missing documentation.
- Analysis as to whether any changes/updates constitute breaking changes
Analysis of documentation corpus to identify needed changes across docs (and any fixes)

If I were doing these steps on my own, I might cut corners with some releases. For example, I probably wouldn’t have time to analyze the log reports or to scan all other documentation for needed updates. The skill helps me do these steps seamlessly.

Additionally, if you define a specific template for publishing, that template gets applied each time you run the skill, which also leads to more consistency."

https://idratherbewriting.com/blog/all-about-skills-intro

#AI #GenerativeAI #LLMs #Chatbots #Skills #Claude #Gemini #TechnicalWriting #SoftwareDocumentation

I tested Sonnet 5 in both low effort and high effort modes for my documentation tasks. While Sonnet 5 in high effort mode delivers some results comparable to Opus, it consumes significantly more tokens than Opus 4.8 in low effort mode. Opus 4.8 low effort remains the more efficient choice for my workflow.

#AI #TechnicalWriting #Efficiency

I tested Sonnet 5 in both low effort and high effort modes for my documentation tasks. While Sonnet 5 in high effort mode delivers some results comparable to Opus, it consumes significantly more tokens than Opus 4.8 in low effort mode. Opus 4.8 low effort remains the more efficient choice for my workflow.

#AI #TechnicalWriting #Efficiency

"Plain English is the discipline of choosing the simplest word that carries the full meaning. It doesn't reduce accuracy. It reduces the cognitive load required to extract accuracy from the text."

https://www.linkedin.com/pulse/plain-english-being-understood-across-time-zones-carrie-warner-wsc1e/

#Writing #Language #TechnicalCommunication #Technicalwriting

"Plain English is the discipline of choosing the simplest word that carries the full meaning. It doesn't reduce accuracy. It reduces the cognitive load required to extract accuracy from the text."

https://www.linkedin.com/pulse/plain-english-being-understood-across-time-zones-carrie-warner-wsc1e/

#Writing #Language #TechnicalCommunication #Technicalwriting

Even with AI providing significant assistance in technical writing, it remains important to aim for content that is as low maintenance as possible.

#TechnicalWriting #AI #ContentStrategy

As a former tech journalist, I wholeheartedly agree with this!!

"A tech writer is that person who, like a seasoned reporter, chases the product news and presents it, making sure that they’ve collected the strongest evidence. It’s a matter of persistence. Like a particularly learned bulldog, the human writer won’t let go of the news: it’s theirs to bring past the finish line, which means going live, even if the outcome is rough around the edges. DevRels, once shunned by tech writers, are being vindicated in that their humanity is the only thing that can stand out in seas of slop.

For years, we have complained about being treated like formatting factories or syntax janitors. Now that AI is taking those tasks off our plates, and with them a certain comfort zone, we seem afraid to admit that our work is about chasing truth and providing fellow humans with direction. We are in the business of empowering people to build incredible stuff through AI, not that of sticking sentences together in files and chunking content using some dialect of XML. We can no longer hide behind chores: it’s time to guide."

https://passo.uno/tech-writing-role-split/

#AI #GenerativeAI #TechnicalWriting #AIAgents #SoftwareDocumentation #TechnicalCommunication #Docs #LLMs

As a former tech journalist, I wholeheartedly agree with this!!

"A tech writer is that person who, like a seasoned reporter, chases the product news and presents it, making sure that they’ve collected the strongest evidence. It’s a matter of persistence. Like a particularly learned bulldog, the human writer won’t let go of the news: it’s theirs to bring past the finish line, which means going live, even if the outcome is rough around the edges. DevRels, once shunned by tech writers, are being vindicated in that their humanity is the only thing that can stand out in seas of slop.

For years, we have complained about being treated like formatting factories or syntax janitors. Now that AI is taking those tasks off our plates, and with them a certain comfort zone, we seem afraid to admit that our work is about chasing truth and providing fellow humans with direction. We are in the business of empowering people to build incredible stuff through AI, not that of sticking sentences together in files and chunking content using some dialect of XML. We can no longer hide behind chores: it’s time to guide."

https://passo.uno/tech-writing-role-split/

#AI #GenerativeAI #TechnicalWriting #AIAgents #SoftwareDocumentation #TechnicalCommunication #Docs #LLMs

Where’s the holistic AI productivity data?

For most of my career I ran a very small company. When you run a tiny company your resources (both time and money) are limited, and you want to use them on the things that will have the most impact. You have to quickly stop doing things that aren’t cost-effective, to avoid “throwing good money after bad”. Ideally, you do a small trial of something new and measure the results before rolling it out more widely, to avoid going all in on something untested. As tech news starts to publish stories about how companies are realising that AI costs more than the humans it was supposed to replace, I’m wondering why it took them so long to figure this out. I’ve spent the last two years watching companies large and small diving headlong into AI. Rarely do I see an attempt to measure the actual costs, financial and otherwise, of that decision.

It’s certainly possible, for a skilled person, to speed up certain processes while also maintaining quality with the use of an agent. I’ve a number of examples that have been successful, and enabled improvements across content sets that would have been hard to justify the work on otherwise.

However, as I document this work I realise how the success of it relies on the things I know. I can spot when the AI tool goes off track, I review its work in the way I’d review the work of a very junior writer. I couldn’t just hand this stuff off to anyone, and them be able to replicate what I can do in terms of the quality of the end result. When you do that, what you get is something that looks on the surface like the same output, but is a pastiche of the result when someone with actual knowledge is behind it.

The same thing seems to be playing out with agentic coding. You can get yourself something that looks like a functioning application. However, without a great deal of knowledge about how to build a functioning application, what you have is often just a reasonably functional mockup. At best you’ve got a handy personal tool that should never escape into production.

Individual productivity enhancements have a ceiling, what you can do with the tools is limited by the need to review the output. As everyone talks about productivity, I’m just not seeing any real research that demonstrates AI is measurably increasing productivity when you take a holistic view.

Individual AI productivity gains

Individually it’s clearly possible to use an LLM to increase productivity. As I’ve already described, a skilled individual can selectively introduce an AI tool to perform specific (usually rote but not quite scriptable) tasks. There are improvements to be had there, but they are similar to the bump you get when you finally figure out how to use a spreadsheet properly, or learn how to automate tasks with some simple coding. If you can already do those things, then AI use can, in some circumstances, automate some additional tasks or make it quicker to create those automations.

This level of improvement is appearing in research data, for example the London School of Economics found in their report Bridging the Generational AI Gap: Unlocking Productivity for All Generations that professionals using AI save an average of 7.5 hours per week. I have a theory that in many cases for non-coders, AI has just solved coding’s image problem, and these gains could have been achieved without AI.

However, another way someone might report increased individual productivity is by shifting the work onto someone else. That might be another person or team—writers end up fixing slop drafts and having to correct obvious errors, code reviewers wade through Pull Requests, and QA teams spend more time dealing with bugs. It also might be your reader or user who now has to wade through paragraphs of slop, is misled by inaccurate documentation, runs into bugs in your app, or finds it inaccessible to them. In this case you might feel more productive, but all you’ve done is move the work around, make someone else’s job or experience measurably worse, and reduce quality.

It’s for this second reason that a holistic approach needs to be taken to truly assess productivity across an organisation. If we look at specific individuals or even teams, we’re likely to miss task reallocation based on AI use.

AI as a forcing function for accessible data

In addition to the issue of task reallocation, there’s another reason why it’s hard to quantify how useful AI actually is. AI tooling has forced a lot of data to become available and easily consumed. This makes it easier to perform non-AI automations.

People who refused to write documentation in the past are now churning out skills, which are documentation. We can use these to easily identify the process needed to achieve tasks. Identifying repetitive processes is the first step of any automation attempt.

Many of my processes are enabled through the easy access to the data required, such as MCP servers, or sites giving me a nice clean markdown export rather than me having to search through messy div soup HTML. This makes more of what I’m doing possible with regular scripting. I’ve found myself moving more things into Python over time, and using the AI tools for more discrete tasks on reliable data returned from a script.

We can’t justify costs we don’t understand

It’s hard to find anything other than anecdata from individuals telling us how AI has made them individually more productive. If AI really was creating measurable improvements in productivity across entire organisations, wouldn’t we be seeing that data? How can we justify the cost (financial, environmental, and human) of AI, if the reality is a relatively small bump in productivity that could have happened by teaching more people to automate tasks using existing tools or simple coding? Why aren’t businesses encouraging people to use non-AI methods where possible, saving the AI only for where it adds value? Given the societal costs, and the benefit to a business of bringing onboard and training people, perhaps on a balance of things even those tasks where AI is needed are better performed by people.

The lack of rigour disquiets me. I’ve been lucky enough to spend the majority of my life working with people who care. The sort of people who like things to make sense, who want to do the right thing, even if it takes longer. We thrived in an industry that prided itself on being data driven. Now so many of us are burning out. It’s exhausting trying to do the work you’ve spent a lifetime building expertise in when people around you are trying to figure out how to replace you with AI, based on vibes that it should be possible. I worry that by the time this all plays out, many of the experienced people the web needs will have left the industry. I see no evidence that AI can come close to replacing the expertise we’ll lose.

Where’s the holistic AI productivity data?

For most of my career I ran a very small company. When you run a tiny company your resources (both time and money) are limited, and you want to use them on the things that will have the most impact. You have to quickly stop doing things that aren’t cost-effective, to avoid “throwing good money after bad”. Ideally, you do a small trial of something new and measure the results before rolling it out more widely, to avoid going all in on something untested. As tech news starts to publish stories about how companies are realising that AI costs more than the humans it was supposed to replace, I’m wondering why it took them so long to figure this out. I’ve spent the last two years watching companies large and small diving headlong into AI. Rarely do I see an attempt to measure the actual costs, financial and otherwise, of that decision.

It’s certainly possible, for a skilled person, to speed up certain processes while also maintaining quality with the use of an agent. I’ve a number of examples that have been successful, and enabled improvements across content sets that would have been hard to justify the work on otherwise.

However, as I document this work I realise how the success of it relies on the things I know. I can spot when the AI tool goes off track, I review its work in the way I’d review the work of a very junior writer. I couldn’t just hand this stuff off to anyone, and them be able to replicate what I can do in terms of the quality of the end result. When you do that, what you get is something that looks on the surface like the same output, but is a pastiche of the result when someone with actual knowledge is behind it.

The same thing seems to be playing out with agentic coding. You can get yourself something that looks like a functioning application. However, without a great deal of knowledge about how to build a functioning application, what you have is often just a reasonably functional mockup. At best you’ve got a handy personal tool that should never escape into production.

Individual productivity enhancements have a ceiling, what you can do with the tools is limited by the need to review the output. As everyone talks about productivity, I’m just not seeing any real research that demonstrates AI is measurably increasing productivity when you take a holistic view.

Individual AI productivity gains

Individually it’s clearly possible to use an LLM to increase productivity. As I’ve already described, a skilled individual can selectively introduce an AI tool to perform specific (usually rote but not quite scriptable) tasks. There are improvements to be had there, but they are similar to the bump you get when you finally figure out how to use a spreadsheet properly, or learn how to automate tasks with some simple coding. If you can already do those things, then AI use can, in some circumstances, automate some additional tasks or make it quicker to create those automations.

This level of improvement is appearing in research data, for example the London School of Economics found in their report Bridging the Generational AI Gap: Unlocking Productivity for All Generations that professionals using AI save an average of 7.5 hours per week. I have a theory that in many cases for non-coders, AI has just solved coding’s image problem, and these gains could have been achieved without AI.

However, another way someone might report increased individual productivity is by shifting the work onto someone else. That might be another person or team—writers end up fixing slop drafts and having to correct obvious errors, code reviewers wade through Pull Requests, and QA teams spend more time dealing with bugs. It also might be your reader or user who now has to wade through paragraphs of slop, is misled by inaccurate documentation, runs into bugs in your app, or finds it inaccessible to them. In this case you might feel more productive, but all you’ve done is move the work around, make someone else’s job or experience measurably worse, and reduce quality.

It’s for this second reason that a holistic approach needs to be taken to truly assess productivity across an organisation. If we look at specific individuals or even teams, we’re likely to miss task reallocation based on AI use.

AI as a forcing function for accessible data

In addition to the issue of task reallocation, there’s another reason why it’s hard to quantify how useful AI actually is. AI tooling has forced a lot of data to become available and easily consumed. This makes it easier to perform non-AI automations.

People who refused to write documentation in the past are now churning out skills, which are documentation. We can use these to easily identify the process needed to achieve tasks. Identifying repetitive processes is the first step of any automation attempt.

Many of my processes are enabled through the easy access to the data required, such as MCP servers, or sites giving me a nice clean markdown export rather than me having to search through messy div soup HTML. This makes more of what I’m doing possible with regular scripting. I’ve found myself moving more things into Python over time, and using the AI tools for more discrete tasks on reliable data returned from a script.

We can’t justify costs we don’t understand

It’s hard to find anything other than anecdata from individuals telling us how AI has made them individually more productive. If AI really was creating measurable improvements in productivity across entire organisations, wouldn’t we be seeing that data? How can we justify the cost (financial, environmental, and human) of AI, if the reality is a relatively small bump in productivity that could have happened by teaching more people to automate tasks using existing tools or simple coding? Why aren’t businesses encouraging people to use non-AI methods where possible, saving the AI only for where it adds value? Given the societal costs, and the benefit to a business of bringing onboard and training people, perhaps on a balance of things even those tasks where AI is needed are better performed by people.

The lack of rigour disquiets me. I’ve been lucky enough to spend the majority of my life working with people who care. The sort of people who like things to make sense, who want to do the right thing, even if it takes longer. We thrived in an industry that prided itself on being data driven. Now so many of us are burning out. It’s exhausting trying to do the work you’ve spent a lifetime building expertise in when people around you are trying to figure out how to replace you with AI, based on vibes that it should be possible. I worry that by the time this all plays out, many of the experienced people the web needs will have left the industry. I see no evidence that AI can come close to replacing the expertise we’ll lose.

I finally made the switch to Opus 4.8 with minimal effort. Previously, using Opus 4.7 for technical writing tasks consumed tokens at an unsustainable rate. Now, with the same workflows and likely some fine-tuning by Anthropic, I managed a heavy load of documentation requests this week. Token consumption is now much more manageable.

#AI #TechnicalWriting #Efficiency

I finally made the switch to Opus 4.8 with minimal effort. Previously, using Opus 4.7 for technical writing tasks consumed tokens at an unsustainable rate. Now, with the same workflows and likely some fine-tuning by Anthropic, I managed a heavy load of documentation requests this week. Token consumption is now much more manageable.

#AI #TechnicalWriting #Efficiency

"An engineer named Siddhant Khare wrote recently about what he called “AI fatigue” — the exhaustion that comes not from creating but from reviewing. Before AI, his day had a rhythm: think about a problem, write code, test it, ship it. After AI, his day became a loop of prompting, waiting, reading output, evaluating output, deciding if the output was correct, deciding if it was safe, fixing the parts that weren’t, and re-prompting. He described it as becoming a quality inspector on a conveyor belt that never stops. The work was faster but emptier. The flow states that used to sustain him — the deep, energizing focus of building something yourself — had been replaced by the shallow, draining focus of judging something you didn’t build.

Not every writer experiences this the same way. For some, the shift is actually liberating. If your day job involves writing yet another SDK migration guide or documenting the fine-grained differences between configuration parameters across product tiers — content you won’t remember in a month — there’s no loss of creative joy when the machine drafts it for you. You become the editor, not the author, and you save your real creative energy for work that matters to you personally. The fatigue isn’t from reviewing; it’s from pretending that all documentation deserves the same emotional investment. Some of it is toil, and outsourcing toil is fine.

But here’s the tension: if you stop caring about the work the machine produces, who maintains the quality? This is where the concept of ownership becomes critical. The tech writers who thrive in this landscape aren’t the ones who wait for engineers to hand them drafts to edit. They’re the ones who own the reference documentation, who run diffs against every API release, who update architectural diagrams, who maintain a single source of truth..."

https://idratherbewriting.com/blog/judging-beautiful-docs-ai-fatigue-podcast

#TechnicalWriting #AI #GenerativeAI #SoftwareDocumentation #TechnicalCommunication #Docs #Programming #SoftwareDevelopment

"An engineer named Siddhant Khare wrote recently about what he called “AI fatigue” — the exhaustion that comes not from creating but from reviewing. Before AI, his day had a rhythm: think about a problem, write code, test it, ship it. After AI, his day became a loop of prompting, waiting, reading output, evaluating output, deciding if the output was correct, deciding if it was safe, fixing the parts that weren’t, and re-prompting. He described it as becoming a quality inspector on a conveyor belt that never stops. The work was faster but emptier. The flow states that used to sustain him — the deep, energizing focus of building something yourself — had been replaced by the shallow, draining focus of judging something you didn’t build.

Not every writer experiences this the same way. For some, the shift is actually liberating. If your day job involves writing yet another SDK migration guide or documenting the fine-grained differences between configuration parameters across product tiers — content you won’t remember in a month — there’s no loss of creative joy when the machine drafts it for you. You become the editor, not the author, and you save your real creative energy for work that matters to you personally. The fatigue isn’t from reviewing; it’s from pretending that all documentation deserves the same emotional investment. Some of it is toil, and outsourcing toil is fine.

But here’s the tension: if you stop caring about the work the machine produces, who maintains the quality? This is where the concept of ownership becomes critical. The tech writers who thrive in this landscape aren’t the ones who wait for engineers to hand them drafts to edit. They’re the ones who own the reference documentation, who run diffs against every API release, who update architectural diagrams, who maintain a single source of truth..."

https://idratherbewriting.com/blog/judging-beautiful-docs-ai-fatigue-podcast

#TechnicalWriting #AI #GenerativeAI #SoftwareDocumentation #TechnicalCommunication #Docs #Programming #SoftwareDevelopment

First-time speakers are warmly encouraged, especially if you’ve done useful docs work but haven’t spoken about it publicly before.

Submit a proposal even if you’re still shaping the talk. We’d be happy to see the idea early.

#IndiaFOSS #WriteTheDocs #TechnicalWriting

First-time speakers are warmly encouraged, especially if you’ve done useful docs work but haven’t spoken about it publicly before.

Submit a proposal even if you’re still shaping the talk. We’d be happy to see the idea early.

#IndiaFOSS #WriteTheDocs #TechnicalWriting

I'm streaming KDE docs:

• right now!
• on https://live.rabbitictranslator.com
• on https://twitch.tv/herzenschein

I'm streaming to both Owncast and Twitch right now.

My shoulder and back are not great today, but I should be able to stream for one hour or two.

Be sure to join and ask any questions related to KDE and I'll try my best to answer them.

Every single stream I do is an Ask Me Anything KDE Edition ™️

#KDE #Linux #Documentation #TechnicalWriting #FurryStreamer #FurryVTuber #VTuber #Owncast #Twitch

"If you are thinking about using an AI agent for documentation, here is what I think matters most.

Teach the agent, do not just instruct it. A prompt that says "write documentation for this feature" produces generic content. A skill that defines your voice, your formatting rules, your page structure, and your verification checklist produces documentation that sounds like your team wrote it. The upfront investment in the skill pays off on every subsequent page.

Make screenshots reproducible. Manual screenshots are the first thing that goes stale. A declarative manifest that can regenerate every screenshot in one command is worth the engineering effort. It changes screenshots from a one-time cost to a maintained artifact.

Phase your work. Even if you are using an agent, "write all the docs" is not a plan. Break it into phases with clear scope and clear deliverables. This gives you stopping points, review points, and the ability to course-correct.

Expect things to break. OCR will misread text. The UI will change mid-sprint. Preview URLs will go stale. The difference between a frustrating experience and a productive one is whether you encode the fix into a skill so it never happens again.

Review everything. The agent does not replace your judgment. It replaces the mechanical work. You still need to read every page, check every screenshot, and verify that the documentation matches what the user actually sees. The agent writes the first draft. You make it right."

https://dev.to/debs_obrien/how-i-documented-an-entire-product-in-4-days-with-an-ai-agent-3338

#TechnicalWriting #SoftwareDocumentation #AI #GenerativeAI #AIAgents #AgenticAI #LLMs

"If you are thinking about using an AI agent for documentation, here is what I think matters most.

Teach the agent, do not just instruct it. A prompt that says "write documentation for this feature" produces generic content. A skill that defines your voice, your formatting rules, your page structure, and your verification checklist produces documentation that sounds like your team wrote it. The upfront investment in the skill pays off on every subsequent page.

Make screenshots reproducible. Manual screenshots are the first thing that goes stale. A declarative manifest that can regenerate every screenshot in one command is worth the engineering effort. It changes screenshots from a one-time cost to a maintained artifact.

Phase your work. Even if you are using an agent, "write all the docs" is not a plan. Break it into phases with clear scope and clear deliverables. This gives you stopping points, review points, and the ability to course-correct.

Expect things to break. OCR will misread text. The UI will change mid-sprint. Preview URLs will go stale. The difference between a frustrating experience and a productive one is whether you encode the fix into a skill so it never happens again.

Review everything. The agent does not replace your judgment. It replaces the mechanical work. You still need to read every page, check every screenshot, and verify that the documentation matches what the user actually sees. The agent writes the first draft. You make it right."

https://dev.to/debs_obrien/how-i-documented-an-entire-product-in-4-days-with-an-ai-agent-3338

#TechnicalWriting #SoftwareDocumentation #AI #GenerativeAI #AIAgents #AgenticAI #LLMs

"The future of enterprise technical documentation will not belong to organizations that merely generate more content with AI. It will belong to organizations that build semantically governed, operationally validated, and explainable knowledge ecosystems around AI generation.

Large language models are remarkable language-generation systems, but they remain fundamentally probabilistic, and no amount of vector-based probabilistic augmentation, recursive prompt gymnastics, or trillions of additional parameters magically transforms probabilistic token prediction into deterministic operational intelligence — regardless of what the AI snake-oil salesmen on LinkedIn insist between inspirational rocket-ship emojis. LLMs predict statistically likely outputs. They do not inherently understand operational correctness, governance policy, procedural safety, rollback integrity, regulatory compliance, or whether the “helpful” configuration change they just suggested is going to quietly detonate a production Kubernetes cluster at 2:13 a.m. while everyone is asleep and the on-call engineer is reconsidering their career choices.

That is not a moral failure of AI. It is simply the architectural reality of probabilistic systems pretending to perform deterministic operational reasoning often enough to make people dangerously optimistic.

This is precisely why deterministic models and governance matter.

Structured content, semantic markup, metadata governance, provenance tracking, DOM Graph RAG, iiRDS frameworks, knowledge graphs, RDF and OWL ontologies, context graphs, deterministic inference engines, orchestration platforms, Docs-as-Tests automation, and runtime observability together create something fundamentally different from prompt engineering. They create governed operational ecosystems capable of supporting trustworthy enterprise AI at scale."

https://medium.com/@nc_mike/deterministic-and-agentic-ai-architectures-for-technical-documentation-3fb2956a1334

#AI #GenerativeAI #DocsAsTests #LLMs #AgenticAI #DITAXML #AIAgents #TechnicalWriting #SoftwareDocumentation

"The future of enterprise technical documentation will not belong to organizations that merely generate more content with AI. It will belong to organizations that build semantically governed, operationally validated, and explainable knowledge ecosystems around AI generation.

Large language models are remarkable language-generation systems, but they remain fundamentally probabilistic, and no amount of vector-based probabilistic augmentation, recursive prompt gymnastics, or trillions of additional parameters magically transforms probabilistic token prediction into deterministic operational intelligence — regardless of what the AI snake-oil salesmen on LinkedIn insist between inspirational rocket-ship emojis. LLMs predict statistically likely outputs. They do not inherently understand operational correctness, governance policy, procedural safety, rollback integrity, regulatory compliance, or whether the “helpful” configuration change they just suggested is going to quietly detonate a production Kubernetes cluster at 2:13 a.m. while everyone is asleep and the on-call engineer is reconsidering their career choices.

That is not a moral failure of AI. It is simply the architectural reality of probabilistic systems pretending to perform deterministic operational reasoning often enough to make people dangerously optimistic.

This is precisely why deterministic models and governance matter.

Structured content, semantic markup, metadata governance, provenance tracking, DOM Graph RAG, iiRDS frameworks, knowledge graphs, RDF and OWL ontologies, context graphs, deterministic inference engines, orchestration platforms, Docs-as-Tests automation, and runtime observability together create something fundamentally different from prompt engineering. They create governed operational ecosystems capable of supporting trustworthy enterprise AI at scale."

https://medium.com/@nc_mike/deterministic-and-agentic-ai-architectures-for-technical-documentation-3fb2956a1334

#AI #GenerativeAI #DocsAsTests #LLMs #AgenticAI #DITAXML #AIAgents #TechnicalWriting #SoftwareDocumentation

The cost of not documenting software AKA why software companies will continue to need to hire and keep technical writers:

"Perhaps bizarrely, "the best documented game" in CD Projekt's history according to Ruciński is spin-off Witcher cardgame Gwent. "In a live service environment, which you could argue Gwent was, it is easy to say that you don't have the time to document everything, because the game is changing so fast," he said. "It receives patches, new content, new balance, every month. So all those documents need to be constantly updated, and somebody has to do that. It is a cost."

The developers opted to "pay this documentation tax upfront", however, rather than kick it down the road. As a result, said Ruciński, "new artists, new coders, new designers could jump onto any task within Gwent and contribute instantly." This demonstrates that "documentation doesn't have to slow you down, you don't have to think of documentation as something that will only be useful years later. Documentation can actually speed you up, make you faster right now."

Things didn't go nearly so well during the creation of Cyberpunk 2077 – a "true test of scale" for CD Projekt's technical writers. "Cyberpunk was a fresh start, but it came with new problems," Fulneczek recalled. "It was a massive undertaking. The hopes and expectations surrounding it were enormous. Internally, we had our documentation tool, Confluence, we had a proof of concept of 'living' documentation, so we thought, we were ready.

"But it turned out we weren't, because Cyberpunk was the first project of this scale, this size that we documented, and it also took a very long time," he went on. "And during those eight, nine years of development, we created over 8000 pages of documentation, and that's because of how complex this project was, and it also had many iterations along the way..."

https://www.rockpapershotgun.com/it-was-chaos-how-the-witcher-4-and-cyberpunk-2-are-learning-from-decades-of-cd-projekts-documentation-mistakes

#TechnicalWriting #SoftwareDocumentation #Documentation #Videogames #TechnicalCommunication

'Good documentation is a tell-tale sign of a great product and a company that puts users first. There exist good products with bad or no documentation, but there are very few poor products with great documentation.'

--John Gruber, https://daringfireball.net/linked/2026/05/12/kagi-snaps

#TechnicalWriting #documentation

I'm streaming KDE docs:

• right now!
• on https://live.rabbitictranslator.com
• on https://twitch.tv/herzenschein

I'm streaming to both Owncast and Twitch right now.

Today I'll continue working on updating plasmoid development docs.

Be sure to join and ask any questions related to KDE and I'll try my best to answer them.

Every single stream I do is an Ask Me Anything KDE Edition ™️

@kde #KDE #Linux #Documentation #TechnicalWriting #FurryStreamer #FurryVTuber #VTuber #Owncast #Twitch

The introduction of Claude Code in my technical writing workflow has drastically shifted the main bottleneck. It used to be during the exploration and discovery phase, either on my own or with the help of an SME. Now that Claude Code assists in that phase, all my documentation requests reach the final review stage much faster. This means more requests reach the final review stage for SMEs, who are struggling to keep up. When the SME is a developer, it adds to their workload, especially with the increase in code reviews as other developers also produce more. These are interesting times.

#TechnicalWriting #AI #Workflow