Home

Adventures in docs-as-code by Kayce Basques

Recent Posts

• Stateful docs site assistants are promising

  Posted on:February 8, 2024 |  at 05:35 PM

  I often think about the people reading my docs in terms of "journeys". Google Search drops them into some random page of my site. The content they really need often isn't on that exact page; they need to click around to a few other pages. Or they're building something complex and the ideas are spread across multiple pages. For a GenAI chatbot assistant thingamajigger to be truly helpful, it's got to be a companion on that journey. "I can't carry it for you, but I can carry you!" It needs to remember your goal, the pages you've visited, and the things you previously said. Most important, I think this could seriously speed up the time it takes our users to Get Shit Done. Bonus, if we can get logs of those chat conversations, we (the docs site maintainers) will have a much better idea about what kinds of journeys our users are actually going on. The video below is a proof-of-concept that stateful docs site assistants are possible.

• Sentry Overflow

  Posted on:February 3, 2024 |  at 04:46 PM

  Just now, as I was searching for the Bash script syntax on how to check if a directory exists (for the 63rd time because I have the memory span of an agitated Chihuahua) I noticed something interesting. Sentry, the app monitoring company, had the top SERP spot.

• Fixing Google Search Console's pesky "discovered but not indexed" error

  Posted on:January 29, 2024 |  at 11:13 AM

  My workflow for solving the "Discovered - currently not indexed" error in Google Search Console.

• Generating page summaries with HuggingFace summarization models

  Posted on:December 6, 2023 |  at 07:40 PM

  Can I use one of the summarization models published on HuggingFace to locally generate summaries for each page of my Sphinx site? The answer after one night of Covid-delirious experimentation appears to be a resounding "maybe"!

• Evaluating the quality of my retrieval-augmented generation system

  Posted on:June 16, 2023 |  at 11:11 AM

  I have a prototype of a retrieval-augmented generation search experience for the Pigweed docs. I need a way to measure whether the various changes I make are improving or reducing the quality of the system. This is how I do it.

• Wrangling verbatim text in a Doxygen + Breathe + Sphinx docs system

  Posted on:June 9, 2023 |  at 11:11 AM

  The Pigweed docs (powered by Sphinx) are using Doxygen and Breathe to single-source their API reference documenation. Last night I was having trouble getting a plaintext diagram to render correctly. This is how I fixed it.

• Software engineers want offline docs

  Posted on:May 31, 2023 |  at 11:11 AM

  I don't have any grand ideas here. I just want to kick off a discussion within the technical writing community about the need for offline docs and how we might go about making our docs more easily consumable in offline contexts. I know that some docs sites already support this. I also know that it's not a new idea. My main question is: should we make it more ubiquitous? If so, how?

• Docs sites with retrieval-augmented generation features

  Posted on:April 30, 2023 |  at 11:11 AM

  This post is an evergreen list of docs sites with RAG features. I will update the post as I discover new ones.

• Fine-tuning an LLM into a style guide editor

  Posted on:April 29, 2023 |  at 11:11 AM

  Style guides usually have far more rules than I can possibly remember all at once while editing a doc. Can I fine-tune an large language model (LLM) to automate the process of editing a doc for style guide rules?

• Response to Tom's "10 principles for writing for AI"

  Posted on:April 21, 2023 |  at 11:11 AM

  This post continues the discussion on how docs strategy might need to change in order to take full advantage of generative AI.

• Positioning your docs to play nicely with generative AI

  Posted on:April 18, 2023 |  at 11:11 AM

  Early ideas about how to author docs that work well with generative AI.

• The role of web service API reference documentation in ChatGPT Plugins

  Posted on:April 5, 2023 |  at 11:11 AM

  ChatGPT Plugins enable ChatGPT to access real-time information. Web service API reference documentation plays a big and important role in the ChatGPT Plugin architecture. You can't force ChatGPT to use your plugin. You can only persuade ChatGPT to do so by documenting your API effectively.

• The curious case of the missing link text automation feature

  Posted on:March 30, 2023 |  at 11:11 AM

  Sphinx's approach to link text improves docs maintainability and reduces toil. Yet, curiously, this feature is absent from most other docs site systems.

• Initial thoughts about the potential impact of generative AI on technical writing

  Posted on:March 24, 2023 |  at 11:11 AM

  A lot of people are talking about how generative AI is a gamechanger for documentation. This post summarizes what's going on.