#technical-writing — Public Fediverse posts
Live and recent posts from across the Fediverse tagged #technical-writing, aggregated by home.social.
-
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
-
Companies Are Making Claude and Codex Talk Like Cavemen to Stop AI’s Soaring Costs: https://www.404media.co/companies-are-making-claude-and-codex-talk-like-cavemen-to-stop-ais-soaring-costs/
In other words, this is when even mid-level managers start to understand why AI is nearly always not good.
#AI #ArtificialIntelligence #TechComm #TechnicalCommunication #TechnicalWriting
-
Companies Are Making Claude and Codex Talk Like Cavemen to Stop AI’s Soaring Costs: https://www.404media.co/companies-are-making-claude-and-codex-talk-like-cavemen-to-stop-ais-soaring-costs/
In other words, this is when even mid-level managers start to understand why AI is nearly always not good.
#AI #ArtificialIntelligence #TechComm #TechnicalCommunication #TechnicalWriting
-
"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.
-
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.
-
"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.
-
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
-
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.
-
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.
-
"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.
-
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.
-
I'm streaming KDE docs:
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."
#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."
#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..."
#TechnicalWriting #SoftwareDocumentation #Documentation #Videogames #TechnicalCommunication
-
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..."
#TechnicalWriting #SoftwareDocumentation #Documentation #Videogames #TechnicalCommunication
-
I'm streaming KDE docs:
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
-
Random plug for a documentation system I really enjoy and got to talk about with someone today.
If you struggle to write (or think about) good technical documentation like I do, you might benefit from learning about Diátaxis. https://diataxis.fr/
It breaks down the different reasons people go to learn and acquire information and it really helped me think about how I want to present information.
-
'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
-
'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
-
I'm streaming KDE docs:
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
-
I'm streaming KDE docs:
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.
-
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.
-
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
-
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
-
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 :)
-
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 :)
-
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
-
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
-
"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
-
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
-
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