"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

It's important to educate people about good practices even in code and configuration examples, especially when it comes to security.

https://github.com/opentofu/opentofu/pull/2764

We all copy/paste code and configuration snippets at some point, and that can cause silly mistakes.

#Security #BestPractices #Documentation #SoftwareDocumentation #DevOps #DevSecOps

@sigue @lisp_discussions

Right.

Documenting requires some self-discipline, too.

May I offer two adages:

If it's not documented, it doesn't exist.

If it's not worth your time documenting your software, is it worth my time figuring out how to use it?

#CommonLisp
#SoftwareDocumentation

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

#TechnicalWriting #SoftwareDocumentation #AI #GenerativeAI #LLMs

Ever wondered how beforeEach works in unit test frameworks? Check out our new lifecycle diagram!

https://qunitjs.com/lifecycle/

People generally guess right when it comes to ordering, so why a diagram?

We want to show that the order is guaranteed, and showcase what's possible when you depend on it.

Thanks to FND, Jan, and NullVoxPopuli for improving and promoting this work! H/T @FND @simulo @nullvoxpopuli

#qunit #WriteTheDocs #TechnicalWriting #SoftwareDocumentation #documentation #TDD

"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

Does anyone have links to resources about what good documentation looks like, and how it should/could be written?

Ideally aimed at documentation for software libraries, but any sort of tech topic is relevant for inspiration.

Links to examples of good documentation are not relevant.

#Documentation #SoftwareDocumentation #PHP #SoftwareCommunication #HumanComputerInteraction

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

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

"Technical documentation as an industry is at a crossroads. If we don't invest in the next generation of experts—consultants, educators, and documentation strategists—we're looking at a future where companies try to automate away problems they don't fully understand, and the only available documentation training is a two-hour webinar hosted by someone who just discovered Markdown last week.

So, if you're an industry veteran, here's my plea: write it all down before you retire. Mentor someone. Record a video explaining why metadata matters. Start a blog. Write a book (or three). Please do something to ensure that when you finally sign off for good, the rest aren't left googling "How to create a sustainable documentation strategy " and getting a bunch of AI-generated nonsense in return.

Otherwise, the future of tech comm might be one long, desperate, less-than-helpful Slack thread."

https://www.thecontentwrangler.com/p/the-great-documentation-brain-drain?r=8sej&utm_campaign=post&utm_medium=web

#TechnicalWriting #SoftwareDocumentation #SoftwareDevelopment #Programming #BrainDrain

Do developers need code samples in API documentation?

https://idratherbewriting.com/blog/code-samples-might-not-be-needed-anymore

#APIDocumentation #TechWriting #CodeSamples #AI #DeveloperTools #SoftwareDocumentation #APIs #AIInTechWriting #DevDocs #TechnicalWriting #APIDocs #Coding #AIvsManual #SoftwareDevelopment

"[W]ith AI-assisted writing, editing, and translation, your proficiency in a specific human language will matter less than your ability in building effective technical communication solutions. It was already like this, but the fact that the code editor I use at work, Cursor, can complete impeccably idiomatic sentences just by hitting the Tab key means that I don’t need to be Hemingway.

In technical documentation, language is a circumstance, an implementation detail. We use English because it’s the lingua franca of technology at the moment, and because most software is being produced, or innovated, in the Anglosphere. For all I know, the main language of tech comms could be Chinese, Hindi, or Indonesian in 2049. The democratization of English through LLMs and AI agents will only facilitate this sort of lateral movement.

The next tech revolution might come from Bangalore, Shenzhen, or São Paulo. The companies best positioned to understand, document, and build upon these innovations will be those with diverse technical writers who can bridge linguistic and cultural divides. In a world where LLMs handle the mechanical aspects of language production, the truly valuable skills become cross-cultural communication and technical comprehension."

https://passo.uno/native-english-tech-writing/

#TechnicalWriting #Language #Communication #LLMs #AI #GenerativeAI #English #SoftwareDocumentation

“Fortunately, I think there’s a good alternative to the dismal picture of brain-dead tech writers pressing buttons on AI machines and passing the content to SMEs for review. That alternative is to focus on what AI algorithms can’t do (at least not with a few button clicks). In this revised approach, tech writers offload the simple tasks to AI tools to fix while focusing their real time and energy on more complex, ambitious tasks that are beyond the straightforward capabilities of AI tools.

When I say beyond AI capabilities, I still mean AI tools might assist or augment tech writers in the work; it’s just that the tasks aren’t as simple as the mechanical tasks of fixing doc bugs that I described earlier (e.g., “what’s the issue? what’s the fix?”).

For example, when I set about creating complex tree diagrams showing all elements in an API, this was a new kind of documentation that hadn’t been done before at my company. It became an instant hit and one that proved challenging to maintain and grow and fix, but still worthwhile. (In fact, in a chat with a product manager last week, he wondered if our tree diagram page wasn’t the most popular page in our documentation.)

If we focused more on these sophisticated tasks (beyond click-button AI), I think tech writers could have a brighter future.”

https://idratherbewriting.com/blog/recursive-self-improvement-complex-tasks

#TechnicalWriting #SoftwareDocumentation #APIDocumentation #AI #GenerativeAI #LLMs #Docs

📁 #FromTheArchive

Crafting #ArchitecturalDiagrams isn’t always straightforward. Even simple diagrams can become tricky or prone to errors if not done thoughtfully.

Consistent and meaningful diagrams are essential for bringing clarity and fostering consensus among diverse stakeholders.

Check out this #InfoQ article for tips on designing diagrams: https://bit.ly/40R6YMe

#SoftwareArchitecture #SoftwareDesign #SoftwareDocumentation