Mastodawn

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

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

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

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

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

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

Developing internal skills for recurring documentation processes like release notes

My hypothesis this year around AI was that if I develop some agent skills to speed up repeatable processes, it might clear up my bandwidth and free up time for me to work on non-repeatable doc tasks. It appears to be working.

I’d Rather Be Writing Blog and API doc course

rachelandrew Apr 21

I had a few days off work last week. My daughter was visiting, and in the evening we sat and watched episodes of Being Gordon Ramsey, a documentary series following the chef as he opens a huge restaurant project in London. It’s an interesting watch, but the thing that comes across through every word and action of Ramsey is how much he cares. He cares about the food, the experience, his family, the young chefs he mentors, and the friends he has made during his long career. The tiny things matter as much as the big ones, and fixing them is important. His high standards apply to himself and everyone around him, because it all deeply matters to him.

Yesterday I saw the following post on Bluesky, and my mind immediately linked it to my thoughts around Ramsey’s documentary.

Claude Design unlocks the project manager’s dream of making the button bigger without pushback. Half of your design team will be fired in a month, the design system and branding guidelines thrown in the trash, and the App Store ratings down one or two points in a few months time.— Jae (@jaehanley.social) April 20, 2026 at 5:12 AM

Before generative AI became a thing, many of the roles that support software engineering could be described as things engineers don’t like doing. There are, of course, plenty of engineers who recognise the skill and craft of people like technical writers and designers, however I’ve also met a large number who see us as people who do the lower value work. Work that engineers absolutely could do, but it’s not worth their time. I’ve seen this very clearly in the way I’m treated as a writer, over how I was treated as a developer.

Now we have generative AI, which can also do this work. To a person who doesn’t care about the craft, some generated documentation or design elements are exactly the same as those handed over by a writer or designer. Someone, or something, else has done the work. However, machines don’t care.

Design systems and editorial style guides need people who care. They need people who care about the small details, who obsess over consistency. They need people who are willing to push back, and who are happy to say no to the endless requests to ignore the guidelines just this one time. Yes, we’re sometimes very annoying to people who just want to ship the app or publish their blog post, but we know that consistency matters. The problem for us is that it’s very difficult to demonstrate the impact of it until it’s gone. Even then, people may not connect the fact that support requests have gone up with poor quality documentation, or poor reviews with an unintuitive UI.

I don’t think this problem is exclusive to these roles. Tech is full of people who care deeply about their area of chosen specialism, and we’re all struggling in a world where doing lots of stuff really fast has become the most important thing.

It’s unlikely that our industry can close the door on generative AI, and I think there is a place for tooling of all kinds in helping to speed up and remove toil from production. However, if those tools aren’t under the control of experts who care deeply about the end result, what you end up with is slop. It’s why I believe strongly that AI-led content operations must be owned by writers. There has to be someone who cares enough to push back, with the experience and organisational power to argue for quality over speed when it matters.

Returning to Gordon Ramsey, the other thing I noted from watching his documentary was how his approach and deep level of care was replicated by his entire team. You might think that perhaps it’s because they are afraid of him, given his sweary Kitchen Nightmares persona. However, the lifelong friendships with people who have worked for him seem to show otherwise. Leaders who care build teams who care, they nurture people who are willing to go the extra mile. Leaders who care develop people who have the confidence to tell others that we need to slow down, fix the issues, comply with the design system or style guide, nail the details, for the benefit of the product and the users.

https://rachelandrew.co.uk/archives/2026/04/21/the-importance-of-people-who-care/

#technicalWriting

getinfotoyou Apr 21

If you spend your days writing documentation or dev blogs, you know the friction of moving between formats. I built Aimarkdownpro specifically for developers and technical writers who just need clean, reliable HTML from their Markdown. It's a free, straightforward web editor that handles the conversion without unnecessary bloat or tracking. Just paste your text and get your markup.

#Markdown #TechnicalWriting #WebDev
https://aimarkdownpro.getinfotoyou.com

AIMarkdownPro - Free Online Markdown to HTML Converter

Convert Markdown to HTML instantly with our free online markdown editor. AI-optimized converter with real-time preview, syntax highlighting, and multiple export formats.

AIMarkdownPro

Miguel Afonso Caetano Apr 20

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

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

#Documentation #DocsAsProduct #SoftwareDocumentation #TechnicalWriting #SoftwareDevelopment

What makes docs beautiful?

Docs are often thought of as a purely functional artifact, a packet of content that, when it works, it’s not remembered at all. Those who consume documentation, however, can tell whether a manual or docs site pleases our mind and senses in ways that others don’t. We know the feeling of a page that lands and the feeling of a page that drags. Now, if we agree that docs can be a product, why not seek to build them in a way that pleases consumers? If docs are the entry point for products, shouldn’t they produce a positive feeling that makes users return to them more often and trust them more? Docs that make users feel empowered, or that leave them with learnings. Docs that heal.

Miguel Afonso Caetano Apr 16

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

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

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

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

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

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

Markus Eisele Apr 13

I took down one of my Quarkus posts.

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

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

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

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

#Quarkus #Java #AI #DevTools #TechnicalWriting

Miguel Afonso Caetano Apr 12

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

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

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

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

The Emerging Picture of a Changed Profession: Cyborg Technical Writers — Augmented, Not Replaced, by AI

I recently gave a presentation to students and faculty in person at Louisiana Tech University on March 30, 2026, focusing on what I call the cyborg model of technical writing. The idea is that the emerging model for tech writing isn’t one in which AI replaces tech writers but rather one in which AI augments tech writers. Tech writers interact with AI in a continuous back-and-forth, conversational, iterative manner. This post contains the recording, slides, transcript, summary, notes, and more from my presentation.

I’d Rather Be Writing Blog and API doc course