I’m doing the Instant Pot test run following the user manual. The user manual is very good—I mean speaking as a professional it’s excellent technical writing. I would use this manual to teach a class in how to do it right. #TechnicalWriting
#cooking #food
"The purpose of documentation is to skill and empower someone in their craft. It serves their acquisition and application of skill.
I have heard it suggested that documentation should now be optimised for consumption by AI. That is like asking how we can make our cities better for cars, or our workplaces better for the furniture.
If creators of documentation are prepared to sacrifice its human purpose in order that LLMs can more effectively slurp it up and regurgitate it on demand, then they have meekly accepted values that more properly belong in a dystopian horror story.
Even if we think about the notion only pragmatically, leaving all values aside, it’s a panicky, inconsidered idea. What possible sense does it make to try to “write for LLMs” when LLMs themselves are evolving so rapidly that their capacities and patterns change from one week to the next?
Human beings are difficult creatures with complex needs, but they have been that kind of creature for thousands of years. Not only have we painstakingly built up deep understanding of them, we are them; we can know them from the inside. A good way of writing documentation for human beings today will still be a good way to do it in a few years’ time."
#Documentation That Developers Actually Read: The Netflix Approach - DEV Community
https://dev.to/teamcamp/documentation-that-developers-actually-read-the-netflix-approach-1h9i
My second video, which if I'm honest is probably the best advice I can give to any one on communication.
Tired Of Unanswered Emails? Try This!
https://youtu.be/bmm38OFzbVQ
“The goal from starting out is to be able to create an API documentation suite from scratch. The minimal viable document, or the minimum the document must contain before it’s released, includes having all the calls covered, a description, even if only one sentence at this point, for every field and call, section overviews, call examples, and examples of each field. I suggest also creating a Postman collection file for each API suite. A Postman collection file is a complete set of all the requests and that each request may be run by clicking it; it’s a convenience to clients.
Being able to create that document indicates the writer’s proficiency in the mechanics of API documentation. There is a sense of accomplishment when achieving this and comfort with this process. And rightly so. They have the privilege now of calling themselves API documentation writers.”
"What are docs for AI agents? How are they different than internal eng docs? Do we really have to maintain the agent docs and eng docs as separate docs sets? This page contains my notes on these questions.
Scope:
I work on developer docs i.e. docs for software engineers. I don’t know how relevant AI agents are for technical writers in other industries or domains.
I’m thinking specifically about docs for AI agents. I’m not sure that an all-encompassing “docs for AI best practices” exists. The way that we optimize docs for RAG-based chatbots (for example) is probably different than the way we optimize docs for AI agents."
My first video on YouTube for The Technical Editor.
"Stop Explaining Things Wrong—Do This Instead"
Most engineers skip the #1 rule of technical communication.
Spoiler: It’s not about what you say, but who’s reading it.
Poor example to introduce the `disabled` HTML attribute:
Lesson: Don't use the same/similar name as the concept being introduced.
```html
<label>
<input type="checkbox" name="ch-box" value="disabled" disabled />
disabled
</label>
```
https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/disabled#examples
"Among the many forms of yak shaving that plague our craft is obsessing over documentation tooling. The more technically minded among us are guilty of spending too much time tightening the screws of some CI pipeline just to save a few seconds when building the docs. As exercises, they’re indeed useful, for they help us practice technical skills that might lead us to becoming docs engineers. Should we park writing the docs over picking static-site generators though?
The danger lies in mistaking the motion for progress. A perfectly tuned pipeline that builds no new useful content is a monument to wasted effort. It’s the equivalent of a chef who spends all day sharpening their knives to a razor’s edge but never actually cooks a meal. The knives are essential, but they are not the dinner. Our tools are essential, but they are not the documentation. The user who is stuck at 2 AM with a failing API call does not care about your elegant build process; they care about finding the answer."
(To the tune of ABBA’s Money, Money, Money)
I write all night, I write all day, to craft the guides they toss away.
Ain’t it sad?
But praise is cheap and tickets close, for all this thankless, perfect prose.
That’s too bad.
A new feature ships, all sleek and grand,
But no one seems to understand.
I wouldn’t be writing docs at all;
I’d fool around and have a ball.
EDIT: Thanks all!! I'm passing along your suggestions.
Anyone know an open-source project, even a small one, that needs API docs created or improved? Asking for a #technicalWriting pro who wants more experience with API documentation. #FOSS #techcomm (bonus points if it hits interests like politics, food, beer, auto racing, mapping/OSM, civil engineering, social good...)
"Our biggest challenge as technical writers is bridging the gap between the tech we document and the users trying to understand it. LLMs provide us with the support we need to build that bridge. But it’s more than just a bridge to the user; it’s a mirror for the self. Running a draft through an LLM allows me to remix, rewrite, and truly understand what I’m trying to say. I’m not mindlessly generating with AI; I’m thinking through AI. It’s the writer’s equivalent to rubber duck debugging.
The tools we build using LLMs also allow our words to materialize as direct product impact and socialize our thoughts inside organizations. Think of the typical debates over a confusing user interface. Before, I used to argue based on my own expertise and intuition. Today, I could say, “I ran our docs through Impersonaid and it got stuck at this exact step. Here’s the full transcript.” Suddenly, my argument becomes a reproducible linguistic experiment"
#AI #GenerativeAI #TechnicalWriting #SoftwareDocumentation #UserPersonas #LLMs #Chatbots #SoftwareDevelopment #TechnicalCommunication
sakurakat.systems/posts/why-ru...
Another month, another blog post
This time it's about why I prefer #rustlang, and it's not because of memory safety :P
#LearningInPublic #TechnicalWriting #TechBlog
Why Rust? - Sakura Kat Systems
We’re thrilled to welcome Prince Onyeanuna and Ezinne Anne Emilia to the stage!
They’ll be sharing their unique journey and insights in "Contributing to AsyncAPI from a Technical Writer’s POV."
From words to workflows, discover how documentation plays a powerful role in open source success. Don’t miss this session if you're curious about non-code contributions!
July 18–19
Lagos, Nigeria
https://conference.asyncapi.com/venue/Lagos
Happy Friday! Sometimes Past Phil is a legend. All too often, Past Phil is a bastard.
Experimenting with LLMs to generate release notes from requirements, email threads, support tickets, and QA reports.
Gemini helpfully "inferred" a config property. It was nice enough to highlight the hallucination in a second round of analysis, but still… so icky.
Writing a storyboard for a short #video demonstrating how to perform a simple task in a software application, and now I feel like I'm directing a short film with the mouse pointer as its protagonist.
It's very arty and has no dialog.
#TechnicalWriting
"How to leverage documentation effectively in Cursor through prompting, external sources, and internal context
Why documentation matters
Documentation provides current, accurate context. Without it, models use outdated or incomplete training data. Documentation helps models understand things like:
- Current APIs and parameters
- Best practices
- Organization conventions
- Domain terminology
And much more. Read on to learn how to use documentation right in Cursor without having to context switch."
https://docs.cursor.com/guides/advanced/working-with-documentation
Haunted manuals lightning talk
I gave a lightning #WriteTheDocs in Portland, and in this post I share the recording and my slide deck.
https://rinsemiddlebliss.com/posts/2025-05-16-haunted-manuals/
I've tried getting writing related work (specifically technical writing) for years and it's ultimately not exactly been as successful as I'd like. (One reason I run my blog, as a writing outlet/show my skills.) Reading about writers getting hired while using AI isn't encouraging.
