technicalwriting.dev#

A blog about technical writing by Kayce Basques.

Accessibility#

Please support “skip to main content”. A feature that makes your docs site much more user-friendly to people who don’t use mouses and only navigate with keyboards.

Migrating pigweed.dev to Bazel. Development log of my journey to migrate a docs site from a GN-based build system to a Bazel-based one.

Link text automation in Sphinx. A killer feature from Sphinx that more docs systems should adopt.
Wrangling verbatim text. My struggles to get a plaintext diagram rendering correctly on a docs site that uses Sphinx, Breathe, and Doxygen.

Exploring the intertwingularity of a docs site. I’m building a web crawler so that I can track how pages in my docs site link to each other and to the outside web more broadly. If a lot of my docs pages link to some particular page, then that page is probably important. PageRank Lite, basically, except with much more focus on intra-site backlinks.
Embeddings are underrated. Machine learning (ML) has the potential to advance the state of the art in technical writing. No, I’m not talking about text generation models. The ML technology that might end up having the biggest impact on technical writing is embeddings. What embeddings offer to technical writers is the ability to discover connections between texts at previously impossible scales.

GenAI Outlook 2023. My initial thoughts on how GenAI might affect technical writing.
Stateful docs site assistants. GenAI chatbot assistants might be very useful if they can serve as companions for the entire journey that readers take when visiting my docs sites.
Evaluating quality in RAG systems. How do you measure whether your retrieval-augmented generation system is improving over time?
Playing nicely with GenAI. Early ideas about how to author docs that work well with generative models.
The role of web service API reference documentation in ChatGPT Plugins. You can’t control when ChatGPT uses your plugin. You can only maximize the chance that ChatGPT uses your plugin by describing your API effectively.
Re: “10 principles for writing for AI”. My response to Tom Johnson’s “10 principles for writing for AI” post.
Generating summaries with HuggingFace models. Initial experiments around summarizing text with HuggingFace models.
Fine-tuning an LLM into a style guide editor. How and why one might fine-tune a generative model into a style guide editor.
Embeddings are underrated. Machine learning (ML) has the potential to greatly advance the state of the art in technical writing. No, I’m not talking about Claude Opus, Gemini Pro, LLaMa, etc. The ML technology that might end up having the biggest impact on technical writing is embeddings.

Sentry overflow. Sentry, the app monitoring company, appears to be competing with Stack Overflow.
Fixing Google Search Console’s “discovered but not indexed” error. How I fixed this error for pigweed.dev.

Focus on decisions, not tasks. A quote from Every Page Is Page One that has deeply changed how I approach technical writing.

Field research methodology. How I approach my field research.
Field research on docs site search boxes. Where should I put the search box on my docs site? What placeholder text should it contain? What should happen when I type stuff into it? What should the search results look like?
SWEs want offline docs. There seems to be unmet demand for viewing documentation websites without an internet connection.
Deeplink to specific PDF pages. Just append #page=X to your URL, where X is a placeholder for the page you want to link to.