Judging beautiful docs, AI fatigue, and tool slop

Judging beautiful docs, AI fatigue, and tool slop | I'd Rather Be Writing Blog and API doc course

AI Book Club

Join us for the AI Book Club, where we discuss popular books about AI and the human-in-the-loop perspective.

Next meeting: June 28, 2026

The Infinity Machine: Demis Hassabis, DeepMind, and the Quest for Superintelligence

Learn more »

The importance of using the right tools (Nov 26, 2023)

Bleeding my brakes (ZAMM series) (Nov 26, 2023)

Main takeaway: How to incorporate intuitive thinking (ZAMM series) (Dec 1, 2023)

Seeing invisible details and avoiding predictable, conditioned thought (Jun 26, 2024)

Why I decided to reread Zen and the Art of Motorcycle Maintenance (ZAMM series) (Nov 26, 2023)

-->

Use cases for AI: Synthesize insights from granular data (Aug 27, 2023)

Use cases for AI: Arrange content into information type patterns (Jul 6, 2023)

Use cases for AI: Develop build and publishing scripts (Jul 19, 2023)

AI and APIs: What works, what doesn't (Sep 28, 2023)

Use cases for AI: Summarize long content (Sep 6, 2023)

Use cases for AI: Understand the meaning of code (Jul 25, 2023)

Use cases for AI: Seek advice on grammar and style (Aug 4, 2023)

Use cases for AI: Create glossary definitions (Sep 4, 2023)

Use cases for AI: Distill needed updates from bug threads (Aug 6, 2023)

Use cases for AI: Compare API responses to identify discrepancies (Aug 28, 2023)

-->

Recent blog posts

Judging beautiful docs, AI fatigue, and tool slop (May 31, 2026)

Review of Max Tegmark's 'Life 3.0: Being Human in the Age of Artificial Intelligence' (May 17, 2026)

AI Book Club discussion recording of 'Life 3.0: Being Human in the Age of Artificial Intelligence', by Max Tegmark (May 17, 2026)

Developing internal skills for recurring documentation processes like release notes (May 4, 2026)

Looking back at the AI Book Club one year in (Apr 28, 2026)

On pace and value -- why is moving slow boring? (Apr 27, 2026)

Frenetic thinking (Apr 26, 2026)

Work expands to fill the space allotted (Apr 26, 2026)

Too much coffee? (Apr 24, 2026)

AI Book Club discussion recording of 'Breakneck: China's Quest to Engineer the Future', by Dan Wang (Apr 23, 2026)

Some thoughts after using AI to help with taxes (Apr 20, 2026)

Podcast: How valuable are agent skills? Conversation with Larah Vasquez and Fabrizio Ferri-Benedetti (Apr 12, 2026)

The Emerging Picture of a Changed Profession: Cyborg Technical Writers — Augmented, Not Replaced, by AI (Apr 5, 2026)

Will tech writers survive AI? Perspectives from two professors, Nupoor Ranade and Jeremy Merritt (Mar 21, 2026)

AI Book Club recording of 'If Anyone Builds It, Everyone Dies' (Mar 17, 2026)

Recording of Automation Engineering 101 for Tech Docs presentation at WTD West Coast Supermeetup (Mar 12, 2026)

Cracking the code on corporate visibility (Mar 8, 2026)

Podcast: Doc testing, skills files, and the guardians of knowledge -- with Manny Silva (Mar 8, 2026)

Nobody knows what it will look like in 2 years (Mar 3, 2026)

Good shot, GUS!!!! How to win at pickup basketball even if you're not all that great (Mar 1, 2026)

Popular series

Prompt engineering for tech comm

Use cases for AI

Reflections on Zen and the Art of Motorcycle Maintenance

Journey away from smartphones

Trends to follow or forget

Simplifying complexity

Value arguments for docs and tech comm

See all series

Archives

2026 • 2025 • 2024 • 2023 • 2022 • 2021 • 2020 • 2019 • 2018 • 2017 • 2016 • 2015 • 2014 • 2013 • 2012 • 2011 • 2010 • 2009 • 2008 • 2007 • 2006 • Browse posts by year

Browse by tag

Browse posts by tag

Search tomjoht.github.io with DeepWiki

tomjoht.github.io is indexed by DeepWiki.

Other tech writing blogs

See the tech writing blog webring: Previous | Next | Random

Judging beautiful docs, AI fatigue, and tool slop

by Tom Johnson on May 31, 2026

categories: ai •

podcasts •

writing •

technical-writing

In this podcast, I chat with Fabrizio Ferri-Benedetti about a variety of topics related to AI and docs, such as applying Italo Calvino's literary principles of lightness and quickness to evaluate docs, the reality of AI review fatigue versus creator fatigue, whether vibe-coded tools are tools slop, developing internal skills for repeatable doc processes, and the utility of running local AI models.

Audio-only version

Links mentioned

Topics covered in this podcast

Narrative essay version of the conversation

Transcript

Audio-only version

Listen here:

Links mentioned

What makes docs beautiful? (Fabrizio Ferri-Benedetti, passo.uno)

Most vibe-coded tools are not for you (Fabrizio Ferri-Benedetti, passo.uno)

AI fatigue is real and nobody talks about it (Siddhant Khare)

Developing internal skills for recurring documentation processes like release notes (Tom Johnson, I’d Rather Be Writing)

Note: These shownotes are AI-generated.

Topics covered in this podcast

Here’s a list of topics we talked about.

Calvino’s literary principles applied to docs — Italo Calvino’s “Six Memos for the Next Millennium” offers qualities like lightness, quickness, and consistency that translate surprisingly well to documentation. Beautiful docs are ones that unburden the reader, conveying complex knowledge without the weight.

What makes documentation beautiful versus brutalist — Docs brutalism is documentation built purely for function — checklists completed, tickets closed — without soul or craft. Beauty in docs isn’t about visual design; it’s about the feeling of mastery that lets a writer explain something complex to anyone, even a child.

Judging docs in the age of LLMs — As technical writers shift from creators to evaluators of AI-generated content, their core value becomes taste and judgment. The ability to distinguish verbose, flat prose from writing that is light, quick, and exact is what separates a seasoned tech writer from an engineer reviewing the same output.

AI fatigue and the shift from creator to reviewer — An engineer’s account of burnout from nonstop reviewing of AI output resonates across the profession. The psychological toll comes from hundreds of small judgments per day, the loss of creative flow, and the feeling of being a quality inspector on an endlessly moving conveyor belt.

Review fatigue versus creator fatigue — Not everyone experiences AI fatigue the same way. Writing a thousand words from scratch can be more cognitively exhausting than reviewing them, and some writers prefer to save their creative energy for personal projects, delegating the mechanical toil to AI.

Ownership and strategy as the tech writer’s edge — The most effective approach to technical writing involves owning the reference docs and the release process — not just editing what engineers hand over. Running diffs against each API release, updating diagrams, and cross-referencing the entire documentation corpus gives writers independent authority.

Tool slop and the vibe-coding explosion — AI has made it trivially easy to create custom tools, but most of them are built for an audience of one and promoted as something greater. The qualities that make a tool worth using — reach, sociality, and finish — require craft, care, and intent that vibe coding rarely delivers.

Developing internal skills for repeatable doc tasks — Building agent skills that automate repeatable processes like release notes creates compounding value. Each run improves the skill through self-reflection, and as models improve, the same skill produces dramatically better results without being rewritten.

The profession splitting into two directions — Technical writing appears to be forking into a DevRel-like path — writers who create foundational and overarching content using real experience — and a pipeline engineer path, where writers tend automated content production systems as context or content engineers.

Local models and the sustainability question — Running AI models locally on consumer hardware offers advantages in cost, privacy, and sustainability. As inference costs remain high and energy concerns mount, local models running on devices like a MacBook Air or a Pixel phone may cover an increasingly significant share of everyday AI use.

Narrative essay version of the conversation

If the podcast were an article, this is what it would read like.

In 1985, the Italian novelist Italo Calvino sat down to write a series of lectures he would never deliver. He died before he could present them at Harvard, but the lectures survived as “Six Memos for the Next Millennium” — a meditation on the literary qualities that would matter most in the century ahead. Among them: lightness, quickness, exactitude. These sound like principles for writing elegant fiction. They turn out to be an uncannily precise description of what separates good technical documentation from bad.

Lightness in documentation is the ability to explain something heavy without burdening the reader. It’s not about being shallow — it’s about having digested the complexity so thoroughly that you can transmit it with almost no friction. You know you’re reading light docs when you barely notice the effort of understanding. The opposite — docs that force you to decode, disentangle, slog through — is what you might call docs brutalism: documentation built for function alone, every page a concrete block, every sentence load-bearing in the most graceless possible way. It works, technically. It doesn’t make anyone want to come back.

This question — what makes documentation beautiful — might seem like a luxury in an era when LLMs can churn out competent prose by the megabyte. But it’s actually the question that matters most right now, precisely because the machines have no taste. They produce text that compiles, that covers the surface, that sounds authoritative. They cannot tell whether what they’ve written is light or heavy, whether it wastes the reader’s time or respects it. That judgment is entirely human, and it has become the central skill of the modern technical writer’s job. It’s also, increasingly, the value proposition — the reason tech writers still get hired. Anyone can prompt a model to generate a draft. Knowing whether that draft is actually good requires years of accumulated craft.

This shift from creator to reviewer is real, and it’s disorienting. 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

[truncated for AI cost control]