Recent content in Posts on Well-Shaped Words
DuckDB is a democratizing influence on data analysis and engineering. Because its creators obviously care about both design and performance, the tool gives more people a chance to do complex data-processing tasks without the mental, financial, and computational overhead that would come with doing such jobs on a cloud platform. As I get better at using DuckDB, I also become more attentive to the…
Learning is deeper and more durable when it’s effortful. —Make It Stick This year I developed a course on an abstruse standard about manufacturing systems. To prepare for the work, I read Make It Stick: The Science of Successful Learning , an accessible and practical book by cognitive scientists that synthesizes various studies in memory and learning. While designing a course isn’t the…
The command line is a text-based interface, and writing is a text-based activity. Shell tools, therefore, are writing tools. Here are some examples that have served me. All scripts assume GNU versions and the Bash shell. Find and replace Replace all instances of an old phrase within a set of MD files. This works best on a Git repo so that you can review the diffs before committing any changes.…
The idea for this post came from Shauna Gordon , who gave me some great tips on how to better handle math functions in Hugo. Thanks, Shauna! The built-in Go math.Round function rounds to integers. So, to round a number to decimals using Hugo, you need to write a small shortcode. The following examples all use the technique described in Round float to any precision in Go . A…
With Hugo inline shortcodes, you calculate values and build complex, dynamic tables without ever leaving the Markdown page. I discovered this technique when I wrote my post to test the accuracy of a sample of ChatGPT–generated values . Rather than copy my calculations into the page, I realized I could use variables and Hugo built-in Math functions to keep the writing and computation in a single…
LLMs are good at processing unstructured data, like internet pages and research papers, and at generating structured output, like code and JSON files. The devil is in the generated details. If they aren’t correct, what’s the use? Testing the correctness of generated data is the goal of my informal experiment, which uses ChatGPT to build a database of information about classic books.…
I was inspired by Ian Cowley’s talk at WriteTheDocs, One glossary to rule them all . For the filename, I’ve adopted the term he used, termbase . Hugo can use data files , like JSON and YAML, to make templates. This feature is often useful for technical writing: The data file can serve as a source of truth, and writers can use its properties wherever they please. For long repetitive…
Earlier this month, I presented a talk at Write the Docs called “Graphs, not trees: a ground-up approach to fixing a docs site.” Thanks to Dennis Dawson for this great sketch Before I write up my thoughts, let me thank some people: Yesica Torrico for being the design brain behind the visuals, style, and overall organization Sviatoslav Abakumov for giving an incisive critique of a quite…
This shortcode is mainly for acronyms and initialisms. That is, abbreviations made from the first letters of the words in a phrase (like NASA or UDP ). For details and usage advice, read the Google Style topic about abbreviations . This shortcode ensures that an abbreviation is always defined on a page and always has an HTML abbr element. It also saves writers from writing verbose, error-prone…
The Forward feature allows you to forward messages… This is one of the most common constructions in technical documents—and one of the least useful. In fact, you can always avoid the phrase “ feature allows you to verb ” and your docs will be better off: The phrase often incorrectly implies an intermediary between a behavior and its result. Even when an intermediary is…
I approach editing with the same creed as a doctor: first do no harm . My constant doubt is I’ll over-edit and change the meaning. This is why I have researched set of practices : to reduce guessing and have a standardized set of quality improvements. However, when reading for fun, I sometimes can’t stop myself from trying to fix sentences that confuse me. Here are two examples of how…
A typical Hugo setup designates one directory for content (the text that people read) and another for presentation configuration (the logic that controls how the text is organized on the page). Such separation of concerns is quite sensible, but it adds some overhead to the writing process. As it turns out, Hugo also supports inline shortcodes , defined directly in the content file. This means you…
When I write headings, I always consider how they’ll look in the auto-generated table of contents (TOC). If the headings are descriptive, the TOC creates a powerful navigation tool, providing: A high-level summary of the overall document A set of entry points to help readers find the sections that most relate to them. I wrote a long post, Most common edits in technical documentation .…
For a long time, I knew nothing about search-engine optimization. I avoided learning about it. I thought that SEO was something for marketers and other mercantile types, not for technical-writing “purists” like me. Of course, this was a silly line of thinking: technical writers should care about SEO. Why wouldn’t I want to make my docs findable? Everybody searches! Besides, how…
Awesome! 10,000 lines of YAML boilerplate Have you ever said “I love reading 10k-line YAML files?” If you have, I suspect you’re a robot. Because if you’re a human, there’s a good chance you don’t love reading 10k-line YAML files. And if you’ve ever worked on an large OpenAPI spec, there’s also a good chance you’ve gotten lost, at least once,…