technicalwriting.dev#

Field notes from the frontier of technical writing.

Categories#

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.

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.
Bookmarks. Embeddings-related papers, projects, etc.

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.