Skip to content

Commit c785b3e

Browse files
Add initial AI blog post (#366)
I wasn't sure the best way to frame this, so started with sharing a great talk from WTD. This is at least a start for writing about AI, and felt like something I could at least ship. I think we need to continue to formalize this into docs, describing the different approaches (RAG, Semantic Search, Community Curation), but that seemed harder than a more "opinion" piece to get started. Refs readthedocs/readthedocs.org#12514 <!-- readthedocs-preview readthedocs-about start --> ---- 📚 Documentation preview 📚: https://readthedocs-about--366.org.readthedocs.build/ <!-- readthedocs-preview readthedocs-about end --> --------- Co-authored-by: Copilot <198982749+Copilot@users.noreply.github.com>
1 parent a52dbec commit c785b3e

File tree

2 files changed

+70
-0
lines changed

2 files changed

+70
-0
lines changed

content/images/ai-brain.jpg

212 KB
Loading

content/posts/docs-ai-tools.md

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
title: How to think about AI and documentation tools
2+
date: 2025-11-24
3+
description: Exploring perspectives on AI tools and their role in documentation.
4+
category: Meta
5+
tags: vision, ai, docs, tools
6+
authors: Eric Holscher
7+
status: published
8+
image: /images/ai-brain.jpg
9+
image_credit: Photo by <a href="https://unsplash.com/@eclipticgraphic?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Ecliptic Graphic</a> on <a href="https://unsplash.com/photos/a-computer-circuit-board-with-a-brain-on-it-_jg8xh2SsXQ?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Unsplash</a>
10+
11+
12+
AI has been a hot topic in docs for the past year.
13+
It's hard to figure out how to use it effectively,
14+
and hallucinations are a significant problem for many users and documentation authors.
15+
16+
My views on AI have been shaped by the talk [Alex Garnett - Docs AI Tooling is Better (and Better for Us) than You Think](https://www.youtube.com/watch?v=6p6LttjaSNM&list=PLZAeFn6dfHplMbtJtidqFFtL7rt3ASNSR&index=9) from Write the Docs Portland 2025.
17+
18+
<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/6p6LttjaSNM?si=VI9UYkG-Z8XNfwaq" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
19+
20+
## Do what you love
21+
22+
The primary takeaway I had from the talk is that we should think more about the parts of documentation we like doing.
23+
Being reflective and intentional about what we enjoy doing is a good practice in general,
24+
and large industry shifts are a great time to do that.
25+
26+
One of his key points was that AI excels at small, focused technical tasks.
27+
Instead of asking AI to write the docs,
28+
we should use it to help with the parts we don't like doing.
29+
Things like translating from Markdown to reStructuredText,
30+
fixing grammar, or generating boilerplate are great places where the drudgery can be automated away.
31+
32+
Keep the human in the loop for creation and editing,
33+
but use machines at the things machines have been good at for a long time.
34+
35+
## Help users discover
36+
37+
In terms of the user benefits of AI,
38+
thinking about it as another path of discovery of the existing content is a great framing.
39+
This presents in two different places:
40+
41+
* Improved search using semantic understanding of existing pages
42+
* Chat interfaces that reference existing documentation explicitly in replies using Retrieval Augmented Generation (RAG)
43+
44+
The big thing here is using the existing content to enable discovery,
45+
not generating new content that may or may not be correct.
46+
**Creating new pathways for users to find the content they need is a great way to leverage AI.**
47+
48+
## Add additional context
49+
50+
On top of the existing documentation,
51+
the talk references the ability to bring all the community spaces into a single interface.
52+
Bringing GitHub issues, forums, pricing, and website information all into a single place.
53+
54+
Allowing LLMs to index user-generated content like forum posts and GitHub issues is a challenge.
55+
The quality and accuracy of this content can vary significantly,
56+
and outdated or incorrect information could mislead users when surfaced by AI.
57+
But bringing in things you control like product pricing,
58+
and website information is a nice element.
59+
60+
I'm personally excited about the larger vision here though,
61+
but it feels like a work in progress.
62+
The dream of being able to leverage community contributions in more spaces has been long held,
63+
and we're getting close to something that could unlock a lot of the value stored up in those old threads.
64+
65+
## Moving forward
66+
67+
We're looking at writing integration guides for many of these AI use cases,
68+
but wanted to share this talk as a starting point for thinking about how to engage with AI.
69+
We're excited about how AI is making written docs even more valuable and useful,
70+
and we'll continue to explore this space and work to integrate it where it makes sense.

0 commit comments

Comments
 (0)