#technical-writing — Public Fediverse posts

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

Stop learning in silence. Sharing your journey deepens understanding, builds quiet confidence, and lets opportunities find you. Discover how learning in public. https://hackernoon.com/how-learning-in-public-speeds-up-developer-growth #technicalwriting

I would love to see more technical articles and books written with the same level of clarity.

"Index 1,600,000,000 Keys with Automata and Rust" (2015) by Andrew Gallant.

https://burntsushi.net/transducers/

#article #rustlang #TechnicalWriting #automaton #datastructures #algorithms

Food for thought: When documenting the behavior of a highly customizable and configurable product or feature based on questions from a single customer, a technical writer should always consider the scope of the final documentation artifact. This requires making a clear distinction between what is specific to that customer and what is generalizable and easily reproducible by all.

If we don't enforce that strict separation, we run the risk of transforming the artifact into a laundry list of uncontextualized items that are mostly unintelligible for the other customers. In those cases involving very specific scenarios, sometimes what the customer really needs is not necessarily more documentation but rather a detailed technical conversation from our engineering team with their developers explaining how they can by themselves find answers for those questions whenever they need them :)

#TechnicalWriting #Documentation #SoftwarDocumentation

A practical, honest guide to technical writing for developers. Start with problems you solved, write like you speak, and build a skill that compounds over time. https://hackernoon.com/a-practical-guide-to-technical-writing-for-developers-who-want-to-start-sharing-what-they-know #technicalwriting

"Back in 2024 I wrote that AI helps me remove boring work at the margins. This is fine for a lone writer, but how to scale this to an entire team of technical writers? How to make the system helpful but not intrusive? These are all questions I’m starting to answer now, partly through experimentation, but also through dialogue with practitioners and colleagues. One answer I’m testing these days relies on GitHub Agentic Workflows.

Following Four modes of AI-augmented technical writing, I thought of a way of distributing tooling effort across all modes through a tiered system where each level holds a different relationship with the writer. The result is four tiers: intake, local assistance, automated governance, and an MCP server that provides reliable knowledge to all. The idea is that AI assists the writer not just while writing, but also before and after they work on docs."

https://passo.uno/agentic-workflows-for-docs/

#TechnicalWriting #AI #GenerativeAI #LLMs #AIAgents #AgenticAI #AgenticWorkflows #SoftwareDocumentation #GitHub #DocsAsCode

#WriteTheDocs just released a bunch of new videos from their most recent conference and unfortunately some of them shill AI, but one video caught my attention and is definitely worth watching: The Most Human Documentation.

It talks about the things to avoid in order to not be mistaken by machine generation, and what it means for your #TechnicalWriting and #Documentation to feel human. The talk comments on this from a cultural perspective and it matches what I've been thinking about recently.

With the rise of LLMs and their gross effect on online text now there's humans that work on humanizing machine content, be it with deterministic tools or with humans. In the end humans prefer content that feels human, and human content continues to provide more value.

Writing isn’t about fame. It’s how developers turn confusion into clarity, build quiet confidence, and create a career that compounds over time. Start today. https://hackernoon.com/how-writing-helps-developers-think-clearly #technicalwriting

I don't agree at all with the statement that "API documentation is not technical writing" and also with the notion a technical writer can't necessary know enough about programming without being a software developer - hint: how many Udemy courses are there about API development, API design and AP programming? Hundreds? Thousands?

Also, nowadays, with tools like Claude Code and Codex, testing APIs through platforms like Postman should be seen as stuff for QA analysts and not exactly for technical writers, since AI tools such as those allow you to have a more contextualized look at what a specific API endpoint does, specifically in terms of edge cases and "odd balls". As a technical writer, I can ask these tools to highlight specific use cases where the endpoint can be really useful.

That's not to say that the process can be completely automated. Not at all. Specially because an how-to guide explaining how to make use of an API endpoint couldn't essentially be completely triggered by an LLM. Besides, for the foreseeable future and probably even beyond that, the final output should always be reviewed by an engineer. In any case, what I'm talking about is totally different from automatically generally API reference documentation.

But there is no point in knowing how to send a request to an API endpoint and the typical response will be - both in case of success and error -, if I, as a developer, don't have a compelling enough reason to use that endpoint. Another totally different thing is an API Integration tutorial, that is, how to integrate a complete API into your own app. But here you will, of course, also need the intervention of a, guess what, TECHNICAL WRITER!! :-D

"I have said that API documentation is not technical writing and that it is a mistake to try. There are many details clients need to have. This includes format, presentation, and client experience."

https://robertdelwood.medium.com/more-about-api-documentation-errors-part-i-969999176c9f

#TechnicalWriting #API #APIs #APIDocumentation #SoftwareDocumentation

That seems a bit similar to what I currently do... ;-)

"To use an analogy about my process, compare the scenario to a senior tech writer (TW) working next to a junior TW, where the senior TW mostly provides observation and feedback (in this analogy, the junior TW represents the AI agent). The junior TW creates some docs and presents them to the senior TW, who leaves comments explaining what needs to change. The junior TW takes notes about all the feedback in a journal. By the end of the process, the junior TW has three pages of notes.

After the process finishes, those notes aren’t lost. They form the basis of the SKILL file. The next time the senior TW sits down with another junior TW (a different one, as the session changed), the new junior TW produces much better output thanks to the notes. With each iteration, the notes get more detailed — anticipating common errors, adding validation checks, laying a foundation so that each step doesn’t build from faulty information. After a dozen iterations, the senior TW finds they have less and less feedback to give.

Eventually, the senior TW no longer needs to sit next to the junior TW in close observation. The junior TW proceeds autonomously through each step in the SKILL and just shows the final result. One key difference from real mentorship, though: the AI agent doesn’t carry any memory between sessions. It reads the SKILL file cold each time. All the “learning” lives in the document, not in the agent. This makes the SKILL file itself the critical asset — if it’s vague or incomplete, the agent’s output regresses immediately."

https://idratherbewriting.com/blog/internal-skills-release-docs

#TechnicalWriting #APIs #APIDocumentation #Skills #AgenticAI #AI #GenerativeAI #LLMs #SoftwareDocumentation

"Docs are beautiful when conceptual docs let the reader see the architecture, or when a tutorial lets them see their own hands on the keyboard. Diagrams and screenshots help, but they often compensate for prose that failed to produce an image on its own. Docs are visible when the reader can close their eyes and still see what the page described."

https://passo.uno/what-makes-docs-beautiful/

#Documentation #DocsAsProduct #SoftwareDocumentation #TechnicalWriting #SoftwareDevelopment

The great thing that Claude Code - or OpenAI Codex - brings to technical writers is that they can assess the accuracy of any piece of documentation that relies on software code, by analyzing the relevant code base(s).

This is extremely helpful because it definitely helps you fact-check your docs against the source code, namely to see if the Subject Matter Experts (SMEs) were bullshitting you or if the docs became outdated due to the cadence of new releases.

Another advantage is that even if you work in an organization with its own QA team, you can help them catch bugs at an earlier stage of the Software Development Life Cycle (SDLC). For example, yesterday I found an inconsistency between how a certain behavior was coded in the backend and how that same behavior was interpreted by the frontend.

And the best thing is that, since Claude Code does not entirely relies on neural networks but rather also uses regular expressions, the results have an higher degree of determinancy than the ones offered by common LLMs. Even though it's not perfect and you always have to tell it where to direct its attention (meaning the name of the most relevant repository) , this ability of taking advantage of a "Ai-based sniffer" for code is terrific.

For all these reasons I believe that every technical writer that doesn't use Claude Code or a similar toll in its own regular workflows will be immensely disadvantaged.

#TechnicalWriting #AI #GenerativeAI #SoftwareDocumentation #Claude #LLMs #GenerativeAI #ClaudeCode #SoftwareDevelopment #QA

I took down one of my Quarkus posts.

Not because the whole thing was bad. A few answers were just off in a way that can mislead people. That is enough.

So I wrote about the part underneath it: how I try to keep AI-infused IDEs and writing workflows grounded in current docs, runnable code, and explicit guardrails.

Also a bit more personal than usual, because I think this part matters.

https://www.the-main-thread.com/p/quarkus-ai-grounding-java-writing-workflow

#Quarkus #Java #AI #DevTools #TechnicalWriting

This article is great in the sense that it describes most of what I'm doing nowadays as a technical writer. I even put different LLMs reviewing each other's drafts, which is a lot of fun. That's why, personally, I can't be so pessimistic as others are currently being. LLMs are just a new technology that you need to incorporate in your workflows. Of course, there are some skills that will probably become atrofied. At the same time, a new set of skills is emerging. If you don't see that. you will be completely left behind. You just need to use these tools by making use of critical thinking.

"After deliberation for a few months, I reached a conclusion about what I wanted to say: the model that’s emerging is a cyborg model of technical writing, a humans + AI combination. This is in contrast to the many articles, which now seem to come at an even faster pace, saying that AI will replace human labor. I realize there’s a lot of opinion on this debate, but my argument for why the humans + AI (cyborgs) model is the winning one, rather than replacement, is because of this observation: almost no tech writers at my work have automated complex processes using AI. And in my own use of AI over the past few years, the model that’s emerged is a close intertwining of machine and human interaction to produce content. I’m talking with AI all day. It’s not doing much on its own without my constant steering, direction, and feedback."

https://idratherbewriting.com/blog/cyborg-model-emerging-talk

#AI #GenerativeAI #LLMs #Chatbots #TechnicalWriting #TechnicalDocumentation #SoftwareDevelopment #SoftwareDocumentation

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 be focusing on the tutorial and API for KNotifications.

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 #Rust #Twitch

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.

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 #Rust #Twitch

I'm streaming KDE docs:

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

I'm using Owncast where you can use emojis freely and join chat anonymously.

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 ™️

Today I'll be retesting the KDE Rust bindings and merge the new docs letting you use KDE libraries from Rust.

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

I'm streaming KDE docs:

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

I'm using Owncast where you can use emojis freely and join chat anonymously.

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

"Can I convince AI to write useful content with minimal input from me? No. The input required is substantial; it's just a different kind of input than writing from scratch. Instead of staring at a blank page, I'm interrogating drafts, verifying claims, reframing angles, and restructuring articles. It's editing rather than writing, but it's not less work.

Can it provide a novel editorial take? Sometimes. The models produce serviceable takes that, with significant editorial shaping, become useful articles. But the novel connections, the thematic throughlines, the "this matters because of what we published last week" insights all come from me.

Can it produce accurate articles? Not without heavy verification. Every single article required factual corrections. Some were minor (wrong pipeline phase names, singular vs. plural). Some were serious (fabricated implementation details, wrong OWASP rankings, misleading CVE framing). The pipeline's verification step catches a small number of them. The rest require an editor who reads critically and clicks every link.

Can I edit out the AI writing tics? Mostly. The automated copy-editing pass handles the obvious markers. The subtler ones take manual work, and I'm still learning which tics I'm missing in my own editing passes.

I still think, for my needs, the pipeline is a useful tool for editorial content production. It's just not the "AI writes the blog" story that the stats at the top of this article might suggest. It's more like "AI produces a structured first draft that an experienced editor spends 90 minutes turning into something publishable." Whether that's worth it depends on what you value."

https://dacharycarey.com/2026/03/26/drafting-editorial-content-with-ai/

#AI #GenerativeAI #LLMs #TechnicalWriting #Writing #Blogging #Blogs

I'm streaming KDE docs:

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

I'm using Owncast where you can use emojis freely and join chat anonymously.

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

I'm streaming KDE docs:

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

I'm trying Owncast today; if it doesn't work well, I might fall back to Twitch.

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

"With AI, the writer’s role moves to what I call context ownership. This is not a soft concept. A context owner is the person in your organization who governs what your AI tools know, how your content is structured, whether the output meets your quality and accuracy standards, and how your documentation systems connect to your product and engineering workflows.

In practice, context ownership looks like this:

A context owner defines and maintains the templates, standards, and structural rules that AI tools follow. Without these, AI produces content that is internally consistent within a single document but inconsistent across your documentation as a whole. Your customers notice, even if you don’t.

A context owner reviews and validates AI-generated drafts against product reality. AI tools do not know what your product actually does in edge cases. They do not know what changed in the last release that hasn’t been documented yet. They do not know that the API endpoint described in the engineering spec was modified during implementation. The context owner does.

A context owner manages the documentation pipeline. In a modern documentation operation, this means version control, docs-as-code workflows, API-driven publishing, and automated quality checks. These are technical systems that require technical management. AI can operate within these systems, but it cannot design, maintain, or troubleshoot them.

A context owner bridges engineering and customer-facing content. This is the function that has never been automated in any transition, and AI has not changed that. Someone has to understand what engineering built, determine what customers need to know about it, and make sure the documentation connects those two realities accurately.
(...)
This is not a diminished version of the writer’s role. It is a more senior, more technical role than “writer” has traditionally implied"
https://greenmtndocs.com/2026-03-25-ive-seen-this-before/
#AI #LLMs #TechnicalWriting #SoftwareDocumentation #ContextEngineering

I'm streaming KDE docs:

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

I'm trying Owncast today; if it doesn't work well, I might fall back to Twitch.

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

I've been testing #zensical since I will have to migrate off of #mkdocs and #mkdocsmaterial.

Across 3 sites, I only had to change one line in the yaml files and run `zensical` instead of `mkdocs`. Total potential migration time for 3 sites, 10 minutes.

Why potential and not complete? Pending blog and OpenAPI spec support. Once those are released, I can finish testing and migrate.

@squidfunk looking good so far. Thanks!

#technology #tech #indieweb #blog #technicalwriting #docs #docsascode

"To begin with, everything you document has to be in a format that's as structured and machine-readable as possible. The key here is to disambiguate as much as you can, even if you have to repeat yourself. So, don't bother with the formatting of your documentation or the look and feel of your API portal. Instead, focus on using well-known API definition standards based on machine-readable formats. Use OpenAPI for documenting REST APIs, AsyncAPI for asynchronous APIs, Protocol Buffers for gRPC, and the GraphQL Schema Definition Language. Whenever possible, store the API definitions in several formats, such as JSON and YAML, for easy interpretation by AI agents.

But that's not enough. If you don't have all your operations clearly defined, AI agents will have a hard time understanding what they can do. Make sure you clearly define all operation parameters. Specify what the input types are so there are no misunderstandings. So, instead of saying that everything is a "string," identify each individual input format."

https://apichangelog.substack.com/p/api-documentation-for-machines

#APIs #APIDocumentation #AI #AIAgents #LLMs #OpenAPI #TechnicalWriting #SoftwareDocumentation #Programming

The problem is that most companies with the resources to properly implement role fluidity only want to hire "unicorns." Having worked in hybrid roles at smaller companies before and after the widespread adoption of LLMs, I must say that it's a recipe for burnout. This is not only because it's difficult to assess the quality of your work, but also because, in practice, companies don't care much about documentation. In reality, you'd mostly be a software developer doing some documentation in your "free time."

Another problem with this model of a fluid software documentation team is that it assumes there are or will be software companies willing to prioritize documentation as a sector that deserves its own department. However, technical writers are often placed under the product umbrella, which isn't necessarily bad. In fact, it's much better than being placed under "marketing." Unfortunately, if role fluidity ever becomes the norm, I'm afraid it will most likely start with engineering.

https://passo.uno/docs-team-of-the-future/

#TechnicalWriting #SoftwareDocumentation #Programming #SoftwareDevelopment #AI #LLMs

For the forseeable future, AI tools will continue to generate such incomplete and sometime hallucinated outputs that there will be a continuing need for a "human-in-the-loop" to not only use several LLMs to review each other's output but to fact-check the final output. Using one LLM alone results in mediocre quality. Using two LLMs results in (sometimes very) good quality. Use three LLMs with human verification for great/outstanding results.

"1,131 people across the documentation industry responded to the 2026 State of Docs survey — more than 2.5x the number of respondents last year. But the size of the sample matters less than what it represents: a genuine cross-section of the people who create, manage, evaluate, and depend on documentation.

Documentation’s role in purchase decisions is stable and strong, and the case that docs drive business value is well established. The shift this year is in what documentation is being asked to do, and who — and what — is consuming it.

AI has crossed the mainstream threshold for documentation, both in how docs get written and how they get consumed. Users are arriving through AI-powered search tools, coding assistants, and MCP servers. Documentation is becoming the data layer that feeds AI products, onboarding wizards, and developer tools. The teams investing in this shift are treating documentation as context infrastructure, not just a collection of pages.

But adoption has outrun governance, and the gap matters. Most teams are using AI without guidelines in place, and documentation carries a higher accuracy bar than most content. After all, one wrong instruction can break a user’s implementation and erode trust in the product.
(...)
Writers are spending less time drafting and more time fact-checking, validating, and building the context systems that make AI output worth refining."

https://www.stateofdocs.com/2026/introduction-and-demographics

#TechnicalWriting #TechnicalCommunication #SoftwareDocumentation #DocsAsProduct #AI #GenerativeAI