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.

Link text automation in Sphinx. A killer feature from Sphinx that more docs systems should adopt.
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.
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.

2024 Machine Learning Review (For Technical Writers). The sequel to GenAI Outlook 2023.
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.
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 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.

The intractable challenges of technical writing. There are 3 intractable challenges in technical writing. I do not believe we will ever be able to completely solve these challenges using only the practices and technologies of the 2010s.
Focus on decisions, not tasks. Docs should aim to help people decide what to do. Only documenting procedures is usually not enough.

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?