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

#TechnicalWriting #AI #GenerativeAI #LLMs #Chatbots #Documentation #SoftwareDocumentation #TechnicalCommunication

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

#TechnicalWriting #TechnicalCommunication #SoftwareDocumentation #AI #GenerativeAI #AIAgents #DocsForAIAgents #Chatbots #DeveloperDocs #SoftwareDevelopment

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

#TechnicalWriting #TechnicalCommunication #SoftwareDocumentation #SoftwareDevelopment #Docs #Documentation

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

The Frontend Dogma Super Bundle 10 https://leanpub.com/b/frontend-dogma-10 by Jens Oliver Meiert is the featured bundle of ebooks 📚 on the Leanpub homepage! https://leanpub.com #css #html #Reference #SoftwareEngineering #Javascript #TechnicalCommunication #books #ebooks j9t@mas.to #WebDevelopment

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

#TechnicalWriting #TechnicalWriter #TechnicalCommunication #LifeLongLearning #SoftwareDocumentation #DocsAsInfrastructure

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

#TechnicalWriting #TechnicalCommunication #Documentation #SoftwareDocumentation #SoftwareDevelopment #AI #Marketing

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

#TechnicalWriting #SoftwareDocumentation #SoftwareDevelopment #Programming #DocsAsCode #Git #Markdown #TechnicalCommunication #MkDocs #VSCode

"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

#TechnicalWriting #Documentation #SoftwareDocumentation #TechnicalCommunication

"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

#TechnicalWriting #Documentation #SoftwareDocumentation #TechnicalCommunication

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

#AI #GenerativeAI #LLMs #Chatbots #TechnicalWriting #TechnicalCommunication #SoftwareDocumentation #SoftwareDevelopment #TechnicalDocumentation #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

#TechnicalWriting #SoftwareDocumentation #Documentation #DocsAsCode #TechnicalCommunication #InformationArchitecture #CCMS

"Let me be blunt.

If your startup offers APIs and you don’t have a portal, you’re lighting developer acquisition money on fire. 💵 🧯🚒

Here’s what a good portal actually does:

Shortens time-to-value: faster POCs, faster adoption.

Reduces support tickets: devs can find what they need.

Builds trust: your API feels stable, documented, and ready.

Increases conversion: when docs show how easy it is to integrate, not just tell.

Still sending PDF onboarding packets to partners?

C’mon, boo. 🥲"

https://www.quetzalliwrites.com/newsletters/developer-portals-dev-friendly-or-dev-frustrating

#DevPortals #DeveloperPortals #APIs #API #APIDocumentation #TechnicalWriter #TechnicalCommunication

"The accompanying diagram is intended to help you quickly decide how to document an API, but particularly a REST API. The first split is just to make sure you are looking for the right kind of API.

Here is some more context to help you decide on an approach and get started."

https://gist.github.com/briandominick/3ffab6be460fbde799aa34e0a42a4299

#API #APIs #APIDesign #REST #APIDocumentation #OpenAPI #DocsAsCode #TechnicalWriting #TechnicalCommunication

"No one’s heard of a starving craftsman, just starving artists, and for a reason. Craftsmen create something people need. You’ve mastered a few important skills and moved up in the company. The important aspect here is that as you reach out to a greater community, you realize that there are plenty of people who are more skilled than you and who are still learning. Learn from them.

Gaining textbook skills or collecting certifications isn’t the point anymore; it’s applying all this knowledge in practical ways. Along the journey, you need to watch out for your best career interests and make sure that what you’re doing is what you want to do. For example, many get lost in promotions that lure them away from what they like doing, whether that’s programming or writing.

Finally, don’t underestimate perpetual learning. This is the key to the long road. Take time to practice, even if your job doesn’t seem to allow it. Learn new skills or apply existing skills in new ways. Along with practice comes failure, but don’t let that discourage you."

https://robertdelwood.medium.com/book-review-apprenticeship-patterns-guidance-for-the-aspiring-software-craftsman-808c95ee478e

#Craftsmanship #Craftsman #TechnicalWriting #SoftwareDevelopment #Programming #TechnicalCommunication

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

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

#TechnicalWriting #TechnicalCommunication #SoftwareDocumentation #SoftwareDevelopment #Docs #Documentation

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

“Don’t cover all the details of the product and the technologies it relies on because no one reads the documentation anyway, right?”

WRONG! If you’re writing for the Web, you can never be sure of the level of computer literacy of the person who has to read your docs. Moreover, you can never know if that person is looking for detailed instructions on how to use a particular feature or API endpoint. Who knows? It might just be something that you or the rest of the team overlooked as secondary.

When it comes to online content, every page is page one. If you want the user to trust you and use your product with confidence, you should strive to provide as much context as possible. For example, if the user is expected to know how to use Node.js and Docker before getting started with a particular CLI-based application, you should explicitly say so at the beginning of the application's tutorial. Ideally, you should not only provide resources for the user to familiarize themselves with these tools, but also explain elsewhere the benefits of using these tools for this application rather than another tech stack.

A documentation site is a highway with no predefined entrances and exits. Any user can start reading it from any point. It's up to you, the content designer, to determine where it logically starts and ends in terms of information architecture, and to make sure there are enough accessible connections to other learning resources along the way.

The learning experience provided to the end user should be analogous to a great technical book like The Unix and Linux System Administration Handbook (1500 pages), which is not only a classic reference, but also a comprehensive resource with a detailed table of contents and index. Although it's regularly updated with new technical advances that have been introduced since the last edition, it still contains the same core.

https://books.google.pt/books?id=f7M1DwAAQBAJ

#TechnicalWriting #SoftwareDocumentation #Documentation #TechnicalCommunication

"[T]o build effective docs you not only need tools and content types, but also a model of needs that documentation must satisfy as a product, or of actions users need to accomplish through docs. This model should be fairly independent from the type of software product you’re documenting, in the same way conceptual models of product design and satisfaction abstract away the specifics. Aiming for a general model is necessary because it helps professionals learn and communicate together.
What follows is my own descriptive model of user needs for documentation, one I’m following to build and arrange documentation today.
The approach I’m proposing here is a model of what user actions the docs are meant to satisfy. The model aims at connecting both UX research and documentation frameworks with a conceptual and functional layer that focuses on two aspects: docs as a product and what users are meant to accomplish through them. It’s an attempt at describing what technical documentation should do. It’s treating docs as a product that someone is going to use to achieve actual goals.
As I said, the core of the model is actions. I’ve identified seven that I think cover a decent amount of goals that a consumer of docs may want to accomplish when using documentation. They represent common patterns in how users interact with documentation across different products and domains. They’re the following, each bearing an alternative term in parentheses: Appraise (Discern), Understand (Learn), Explore (Discover), Practice (Train), Remember (Recall), Develop (Integrate), and Troubleshoot (Solve)."

https://passo.uno/seven-action-model/

#TechnicalWriting #Documentation #TechnicalCommunication #UX #DocumentationFrameworks #UXResearch #DocsAsProduct