technicalwriting.dev§
Field notes from the frontier of technical writing.
Categories§
Analytics§
Export Google Analytics data to Sheets via Apps Script. This tutorial shows you how to use Google Apps Script to export your Google Analytics data to Google Sheets. The data automatically updates every night. There’s also a custom menu item within Sheets to update the data on-demand. You can also optionally also expose the data over HTTPS to the public internet.
Links§
Link text automation in Sphinx. A killer feature from Sphinx that more docs systems should adopt.
Deeplink to specific PDF pages. Just append
#page=Xto your URL, whereXis 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.
Machine learning§
Embeddings§
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.
Yearly reviews§
Miscellaneous§
Sphinx§
Link text automation in Sphinx. A killer feature from Sphinx that more docs systems should adopt.
The good, the bad, and the ugly of managing Sphinx projects with Bazel.
Strategy§
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.