Documentation is not trivial and AI-generated documentation sucks. As a technical writer, I find somewhat offensive this kind of pretentiousness from software developers. Documentation needs context, intentions, AND real-life use cases. And why the hell would you want to "synthesize documentation"? When you have great information architecture as well as supporting videos, there's no need to synthesize anything at all for the users.

"Clearly LLMs are useful to software engineers. They can quickly generate code, and they are excellent at synthesizing requirements and documentation. For some tasks this is enough: the requirements are clear enough, and the problems are simple enough, that they can one-shot the whole thing.

That said, for anything non-trivial, they are not capable of maintaining enough context accurately enough to iterate to a working solution. You, the software engineer, are responsible for ensuring that the requirements are clear, and that the code actually does what it purports to do."

https://zed.dev/blog/why-llms-cant-build-software

"[W]hat we are doing is shepherding AI, limiting it to certain contexts. We are learning where it’s best to call it, how is best to feed it. And what to do with the output. So is it looks very much like an editorial process, an editorial workflow where you provide some initial input, maybe some some idea on what content to produce, then you review it. There’s always that quality assurance, quality control side, the supervision.

AI is not really autonomous. It relies a lot on us. And I feel like sometimes there are days where, when coding through AIs or doing some assisted writing, I’m spending more time helping out the AI doing the actual task that I’m asking the AI to do. But I take this as a learning process. I read this article the other day, Nobody knows how to build with AI yet. And it was a developer saying that they haven’t quite figured out how to best work with AI. There were lots of comments around the fact that you have to spend lots of time, you have to learn how to talk to it, and when the model changes, you have to also maybe change something you’re doing. You have to learn how to optimize your time. But your presence is always mandatory.”

https://passo.uno/webinar-ai-tech-writing/

"While haste and speed often get confused, they differ in that the second shows control instead of panic. You can maximize speed while keeping accuracy quite high; beyond a certain point, though, spending more time on accuracy, style, or other aspects that prevent a document from going live always yields diminishing returns.

Nobody reads perfect yet outdated docs, except historians. Even then, docs aren’t perfect, because documentation can’t ever be perfect. This is a key principle I stand by (call it the Ferri Paradox if you want): Any document describing a system is necessarily inaccurate. And yet, this reality doesn’t significantly alter the impact of our work, because we aim for simplicity and usefulness over extreme faithfulness. Given how imperfect products are, docs are a charitable portrait.

Now, how you write docs quickly depends on a number of factors. Some of those factors you can’t control: your overall amount of experience as a writer, your initial expertise with specific technologies, and the way features are developed and released in your organization. But other aspects are yours to act upon. For example, you can decide how to best use the technical resources at your disposal and how to approach writing the docs and asking for feedback."

https://passo.uno/how-write-tech-docs-quickly/

"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."

https://vurt.org/articles/my-favourite-german-word/

"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."

https://technicalwriting.dev/ai/agents/

"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."

https://passo.uno/things-tech-writers-shouldnt-care-about/

"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

https://passo.uno/thinking-better-through-ai/

"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

"Your voice must be heard. Inside of your work, you need key stakeholders and teams to know what it is that you do and the value you bring to product development. Your docs are vital infrastructure, but folks won’t realize that until it’s too late. Unless, of course, you become an ambassador of your craft and start making yourself heard and present everywhere. One of the first things I did when I joined a startup was sending an email to the team telling them what I did. It became my first post.

Outside of work, this task is equally important, because tech writing has a depth issue. You must develop a sense of pride in technical communication as a vital discipline. Don’t shy away from intellectual engagement and contribute to the field by sharing your own thoughts, theories, and errors. Some career ladders label that as “thought leadership”. It’s really about showing up and owning the conversation around what we do and why it matters, moving beyond praxis to noesis."

https://passo.uno/how-to-grow-senior-tech-writer/

"Welcome to the State of Docs Report 2025, bringing together insights from documentation experts from across the industry.

This comprehensive report explores how teams track their docs’ success, the future of the industry, the ongoing impact of AI on documentation, and much more.
(...)
We received responses from 444 hands-on documentation experts — including technical writers, managers, engineers, support teams, designers, marketers, and developer advocates. This variety shows just how many teams are involved and invested in documentation today.

We also conducted interviews with a number of technical writers, engineers, and documentation leaders from across the tech industry to get their insights into specific areas — you can read quotes from them throughout the report.

TAKEAWAYS:

- 54% believe their docs generate at least as many leads as their marketing sites

- 42% think AI will let us build docs that intelligently adapt to user needs

- 46% of large companies have decentralized or hybrid docs teams"

https://www.stateofdocs.com/2025/

“When I say that tech writers should own the prompt that generates documentation, I mean two things: that they should design and maintain the prompts, and that they should spearhead docs automation initiatives themselves, as I suggested in my tech writing predictions for 2025. It’s not just about using LLMs at work or tolerating their existence: writers must lead the way and own the conversations with AIs around docs.

What Aikidocs aims at showing is that you can work with an LLM as you would with a tech savvy intern: you provide a style guide, concrete guidance, and source materials to get acceptable output on the other side of the black box. All the content created in those carefully fenced pens will follow your content strategy more than if you let opinionated tools do it for you.

It’s not vibe coding: it’s LLM surfing.”

https://passo.uno/build-tech-writing-tools-llms/

"Most guides to docs like code, even the ones for non-devs, assume you have some developer knowledge: maybe you're already using version control, or you've encountered build pipelines before, or you're working alongside developers.

This guide is for the people who read that paragraph and wished it came with a glossary. This is docs like code for people who don't know what git is and have never installed VS Code.

This post explains terminology and concepts, to help you get a mental model of what's going on. If you prefer to dive in and pick up concepts as you go, skip straight to the tips in How to learn, and come back to the conceptual info as needed."

https://deborahwrites.com/blog/docs-like-code-basic-intro/

"When evaluating documentation’s role, consider these broader strategic questions:

- Strategic positioning: How does documentation support the company’s core strategic approach?

- Competitive advantage: Can documentation create or enhance the company’s unique market position? What type of documentation does the competition offer?

- Value proposition: How does documentation contribute to the product’s overall value for customers?

- Knowledge management: How does documentation support internal knowledge retention and transfer?

- Customer lifecycle: How can documentation improve customer acquisition, retention, and satisfaction?"

https://www.thegooddocsproject.dev/blog/making-business-base-know-company-goals

"When evaluating documentation’s role, consider these broader strategic questions:

- Strategic positioning: How does documentation support the company’s core strategic approach?

- Competitive advantage: Can documentation create or enhance the company’s unique market position? What type of documentation does the competition offer?

- Value proposition: How does documentation contribute to the product’s overall value for customers?

- Knowledge management: How does documentation support internal knowledge retention and transfer?

- Customer lifecycle: How can documentation improve customer acquisition, retention, and satisfaction?"

https://www.thegooddocsproject.dev/blog/making-business-base-know-company-goals

"You can replace tech writers with an LLM, perhaps supervised by engineers, and watch the world burn. Nothing prevents you from doing that. All the temporary gains in efficiency and speed would bring something far worse on their back: the loss of the understanding that turns knowledge into a conversation. Tech writers are interpreters who understand the tech and the humans trying to use it. They’re accountable for their work in ways that machines can’t be.

The future of technical documentation isn’t replacing humans with AI but giving human writers AI-powered tools that augment their capabilities. Let LLMs deal with the tedious work at the margins and keep the humans where they matter most: at the helm of strategy, tending to the architecture, bringing the empathy that turns information into understanding. In the end, docs aren’t just about facts: they’re about trust. And trust is still something only humans can build."

https://passo.uno/whats-wrong-ai-generated-docs/

"The following are my suggestions regarding what else to consider for each of Daryl White’s excellent questions about choosing a toolset for documenting a software product or project.

I have appended a brief guide to the main/broad categories of documentation toolsets and some of the platforms/components that are popular in each.

Finally, this resource ends with a table of possible solutions for various scenarios you might find yourself in.

Before we start with the existing list of questions, I want to highlight one that I think is most important of all, but which is often assumed by people who create these kinds of guides, as they tend to come from one or another world already.

What are you documenting?

When it comes to software technical writing, the more appropriate way to ask this might be: For what user roles is your documentation intended?

For graphical end-user interfaces (GUIs), the largest range of docs tooling is available, but here some of the more commercial turnkey tools have most of their advantages.

For administrator interfaces (installation, configuration, etc), again any tooling will work, but we start seeing real advantages for lightweight markup, codebase integration, and version control.

For developer interfaces, docs-as-code offers significant advantages. Developers can better contribute directly, and it’s generally friendlier for coded samples. APIs (native and remote), SDKs, and CLIs are almost certainly best documented in a docs-as-code environment, even if you integrate it with a more conventional platform for end-user docs."

https://gist.github.com/briandominick/d4cbe11228de0ebe31cda630976af4ef

"[E]ven thinking about the right approach for documentation, apart from the documentation artifact I end up producing, is a form of thinking. And this is my larger point, more than the specific logic of my actual argument. Deciding on the approach is a form of thinking that technical writers engage in. Even when we use AI tools to streamline documentation, it doesn’t mean we’re removing ourselves from thinking and reflection. As long as we’re still engaging somewhere, I think Warner would approve. In this way, we use AI tools to augment and amplify the scope of our thinking, not reduce it."

#AI #GenerativeAI #Writing #TechnicalWriting #SoftwareDocumentation #TechnicalDocumentation #TechnicalCommunication

https://idratherbewriting.com/blog/jonathan-warner-more-than-words-book-review

Hire more technical writers: Isn't the solution obvious?? :-D

"Documentation was especially valuable when it came time to refactor code by providing a blueprint that saved time and improved focus. The researchers found that good documentation “ensures that refactoring efforts are directed towards tangible and specific quality improvements, maximizing the value of each refactoring action and ensuring the long-term maintainability and evolution of the software.”

As our co-founder Joel Spolsky put it, documentation encodes generational wisdom that goes beyond the simple specs of what was built. “Think of the code in your organization like plumbing in a building. If you hire a new superintendent to manage your property, they will know how plumbing works, but they won’t know exactly how YOUR plumbing works,” said Spolsky. “Maybe they used a different kind of pump at their old site. They might understand how the pipes connect, but they won’t know you have to kick the boiler twice on Thursday to prevent a leak from springing over the weekend.”

If we know from decades of research that documentation is a key component of creating and maintaining quality code, why is it so often considered low-priority work developers would rather avoid if they can be writing code instead?
(...)
By embracing AI-powered documentation tools, development teams can significantly reduce toil work, mitigate technical debt, and foster an environment where developers can thrive. Wise organizations will also keep humans in the loop, ensuring that documentation engineers or technical writers act as editors and stewards of any AI-generated documentation, preventing errors or hallucinations from creeping into otherwise accurate docs."

#Documentation #SoftwareDocumentation #TechnicalWriting #SoftwareDevelopment #Programming

https://stackoverflow.blog/2024/12/19/developers-hate-documentation-ai-generated-toil-work/

"[T]he lack of a clear entry path makes the profession less accessible, contributing to a lack of diversity in tech writing teams. If technical writing is to remain relevant in an industry that values innovation and inclusion, it needs to welcome new voices.

Fixing this problem won’t happen overnight, but there are steps companies and the broader industry can take to rebuild the pipeline for entry-level talent:

- Reintroduce mentorship programs.
- Companies can pair senior writers with juniors to share knowledge and help newcomers build confidence.
- Redefine “entry-level” roles.
- Stop asking for years of experience in entry-level job postings. - Focus instead on transferable skills like writing, research, and adaptability.
- Create apprenticeships or internships.
- Paid opportunities to learn on the job can give aspiring writers the experience they need to land full-time roles.
Invest in training.
- Documentation teams should have budgets for upskilling new hires — not just hiring pre-trained professionals."

https://willkelly.medium.com/how-the-technical-writing-profession-betrayed-entry-level-tech-writers-8a0c05617efd

"Tech comms can be a business, but thinking is not selling: it requires intellectual freedom and courage. Leaving these conversations to engineers risks turning technical communication into a caricature of itself, a four-quadrant fantasy devised to lure developers into thinking that documentation is a simple pastime, yet another Jira task.

Only independent thought can help us progress and navigate uncertainty, including our future in a world where AI is injected into every domain that deals with words. Technical writers must own their problems and the conversations around them, or they will slowly fade into irrelevance, their problems absorbed by other disciplines that have more pressing problems to focus on. And if you’re reading that we should lobby more, you’re not wrong: defending knowledge requires power.”

#TechnicalWriting #TechnicalCommunication #SoftwareDocumentation #CriticalThinking

https://passo.uno/tech-writing-depth-issue/