#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
-
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
-
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
-
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
-
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
-
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
-
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
-
"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
-
"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.
-
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
-
"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
-
"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.
-
Hey people in the #UnitedStates, is it worth applying for jobs on #LinkedIn? Specifically in #TechnicalWriting, #Proofreading, and Document #formatting?
I have not heard good things.
-
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
-
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
-
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.
#ai #business #technicalWriting -
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.
#ai #business #technicalWriting -
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.
#ai #business #technicalWriting -
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.
#ai #business #technicalWriting -
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.
#ai #business #technicalWriting -
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.
-
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.
-
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
-
"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
-
"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.
-
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.
-
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
-
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
-
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
-
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