Recent content on This is important
AI tools make it easier than ever to generate content. With that ease, nearly anyone can become a contributor to the documentation. When people are using AI tools to create documentation, how do you maintain the quality, consistency, and accuracy of the content? Fabrizio Ferri Benedetti proposes defining an AI policy for your documentation , with key recommendations to outline principles for using…
I’ve written this post for years — comparing Spotify Wrapped with my Last.fm data, exploring how Spotify put together their music data categories and how the results of Spotify Wrapped doesn’t quite capture my music taste, pointing to my Last.fm data instead (I’m especially proud of last year’s deep dive ). It’s still relevant to compare these different patterns, but…
If you find yourself worried about being left behind because you don’t know what to do about AI and technical writing, this blog post is for you. Lots of people are using AI. As Anil Dash puts it in his blog post I know you don’t want them to want AI, but… : using AI tools is an incredibly mainstream experience now . Even if you’re not personally using AI, many readers of the…
You can lead a horse to water, but you can’t make it drink. In this metaphor, technical documentation is the water. You can spend a lot of time making the pond look nice and accessible. Provide clear, clean water, some lily pads, a water feature to make it easier to drink. You invest in the structure of the pond to make sure the water doesn’t get stagnant, and even add a nice sign to…
A few weeks ago, I gave a lightning talk about music metadata. It’s one of my favorite niche topics to research, so talk covers a lot of what I know about music metadata. Welcome to my talk about music metadata. In this talk, I’ll cover what music metadata is, how it’s made (because it’s not discovered!) as well as what it’s used for — and why it matters. If you want…
Robin Sloan asks: Is the doc bot docs, or not? He relates a recent experience he had with an AI chatbot where the chatbot provided a response for his question that was incorrect despite being provided from the authoritative context of the official Shopify documentation. Reacting, Sloan considers: I suppose there are domains in which just taking a guess is okay; is the official documentation one of…
Data requires maintenance to stay accurate. For machine-generated data, monitoring the structure to ensure you’re collecting valid records is probably enough maintenance. For other types of data, however, it’s a bit more involved. Geospatial data, for example. Molly Taft, writing for Wired in Trump Cuts Are Killing a Tiny Office That Keeps Measurements of the World Accurate shines a…
As someone who does a lot of armchair-yet-informed speculation about how various things get defined in music metadata , this deep dive into how keywords and entity relationships have been formed by Google over the years was fascinating to me. Deborah Carver, based on her years of expertise in the content industry, explores where SEO keyword data comes from in CT No.112: Demystify your algorithms:…
Back in 2021, writing about the seemingly-objective Supreme Court Justices making politicized decisions, Benn Stancil interrogates the idea that data-driven decisions are equivalent to objective decisions in Tilt and tilted : Making arguments from data, like interpreting the law through legal deliberation, isn’t inherently problematic. Quite the opposite, in fact—to the extent that it’s possible,…
I do almost all of my writing in Google Docs and VS Code. Occasionally I’ll take longhand notes or jot things down in Apple Notes, but the real content that I write at work and for this blog is in one of those locations. My VS Code setup When I’m working in VS Code, I use several extensions to help make my work as easy as possible. Code Spell Checker Markdown All in One Markdownlint…
I did most of my year-end discussion in my post How did my listening evolve? Spotify Wrapped 2024 , but I wanted to spare a post for my favorites (subjectively, not quantitatively) of the year. As a shortcut, I put most of the items on my lists that are available on Bandcamp in this Buy Music Club list . Best albums of the year SWIM - In Circles (95 listens) This scratched an itch in my brain that…
Over the years the dominant genres in my music taste have evolved, from mostly pop-punk in the early aughts, to primarily indie rock and bloghouse music in the late aughts, to house in the early tens, and now a much wider variety of electronic music, including UK garage and some trance. As what and how I listen to music has changed over the last 20 years, the way I discover music has too. Digital…
It’s time for my annual deep dive into Spotify Wrapped! I continue to primarily listen to music I own and diversify my streaming habits beyond Spotify to include SoundCloud and YouTube as well. As a result, my Spotify Wrapped is less and less representative of my actual listening history. Let’s dig into my top artists and tracks of 2024 according to each service, and dive into the…
Tianyu Fang researched a long and detailed essay called Whose Domain Is It? , detailing the politics of the Internet’s domain names, especially the country-code top-level domains (ccTLDs) that you might not realize are actually associated with countries. The unexpectedly popular ccTLDs can operate like a tourism effort, at least in terms of generating unexpected revenue for small countries:…
Most of the Internet is held together by best practices and good intentions, and WHOIS servers are one of those. One security company was investigating vulnerabilities in WHOIS and got a whole lot more than they bargained for : Each TLD (the bit at the end of the domain), you see, has a separate WHOIS server, and there’s no real standard to locating them - the only ‘real’ method being examining a…
The UK will give sovereignty of Chagos Islands to Mauritius : Half a century or more after the UK relinquished control over almost all its global empire, it has finally agreed to hand over one of the very last pieces. It has done so reluctantly, perhaps, but also peacefully and legally. The Chagos Islands are also known as the British Indian Ocean Territory, to which the .io ccTLD is assigned.…
A recent post from the American Alpine Club has me considering the potential duty of care that websites like AllTrails and Mountain Project owe to their readers. In The Prescription—July 2024 , the editor Pete Takeda describes two incidents, one where two people were stranded due to their inexperience climbing snow, and another where one person in a group of nine slipped and fell to her death.…
What’s next for you in your career? It’s tempting to focus on the bare minimum — staying employed — but identifying new areas of professional development or focus can help you grow your career and find whatever enjoyment you can from the capitalist toil that is an obligation of modern life. While I was at Splunk, Susan St. Ledger gave a talk about approaching her career with a bucket…
Docs as code is a much-vaunted workflow and toolchain for writing, publishing, and maintaining technical documentation — but in practice, docs as code doesn’t deliver on its promise. What is docs as code? According to the Docs as Code page in the Documentation guide for Write the Docs: Documentation as Code (Docs as Code) refers to a philosophy that you should be writing documentation with…
After I published Should you add screenshots to documentation? , I got some comments from folks who prefer GIFs to screenshots because GIFs can more clearly show how to use a complicated user interface. I agree that GIFs are cool and useful, but they’re also MUCH harder to keep up-to-date than screenshots and have extra accessibility considerations if you decide to use them. WCAG level A standard…
2023 has been a weird year in music for me! I discovered a lot of new-to-me corners of music, didn’t go to very many shows by my standards, and largely flitted between new and familiar artists all year. Let’s dig in… Each section of this post is pretty standalone, so feel free to skip around: Top artists of 2023 Hey Rosetta! and Bon Iver Barry Can’t Swim Overmono Sofia…
Inspired by Matt Webb’s post 10 blogs for your newsreader , I decided to share my own favorite blogs to follow. I also use RSS feeds to consume most of the content I encounter, and always get sad when a site doesn’t provide an RSS feed to let me follow new posts. I end up following many newsletters through RSS as well, because I’m better about keeping up with my feeds than I am…
Most web content is designed to display with a strict hierarchy, tree-based or otherwise. What if it wasn’t? What does it mean to display content as a graph? Why hierarchies are common Why use something different? Serve multiple mental models Write better documentation Improve content reuse Improve machine legibility Why don’t we display content as a graph? It’s difficult to…
Screenshots in documentation can be a contentious topic — some people really like them and think they add a lot of value, while others dislike them due to the maintenance burden and accessibility issues. As a technical writer, I avoid adding screenshots to documentation as often as possible. In my mind, an outdated screenshot is one of the fastest ways to lose customer trust, so if I’m not…
For months, there have been reports on deteriorating search quality 1 . As the quality of search results deteriorates, so too does an important factor that makes technical documentation so useful — its findability. In an era of web-first authoring and product-led growth marketing strategies, organic documentation findability matters. For some software documentation sites, at least 80% of traffic…
How you choose to make technical content available online sends a message about how you do business and what you think about your content and customers… 🌐 Available fully for free on the web : You want your technical content to be as easy to find as possible. You want it to be easily searched, shared, and copied. You don’t mind if competitors know how your product works, because you also…
Heather Buchel’s post It’s 2023, here is why your web design sucks about the current state of web design (and web app design) resonated with me, especially this quote: “Design decisions can only be pushed so far to the left before we realize the system is broken” If you bisect design and development into different professions, you can end up with designers that aren’t…
As a tech writer, I’ve encountered a number of different processes that teams and companies have used to add documentation to their product development processes. Some of these are intentional and others are incidental—but all are used to create documentation across the software development industry. At its most basic, the product development life cycle involves the following steps:…
There’s been some discussion about the challenges of implementing LLMs , but I haven’t seen any comments about the effect a large language model-based chatbot could have on a company’s user community. Implementing an LLM-based chatbot seems like an excellent way to do two important things: Help people find information about your product Collect data about the information people…
Products use machine learning and “artificial intelligence” to do things like recommend a song to listen to, offer a quick response to an email, organize search results, provide a transcript of a meeting, and more. Some products rely on ordinary data analysis to construct insights about things like your business performance in a market, or the conversion rates for your online shopping…
I follow as much discourse around ethics in machine learning, data analysis, and artificial intelligence as I can. These are the resources I’ve used over the years to help me gather knowledge and perspectives and form my own opinions about these types of technology and implementations. I’ve co-presented two talks on machine learning bias, and gave another on my own about the effects of…
There’s value in the holes. If you search for information about a topic and don’t find very much about it, it can be a clear signal that more research is necessary or desired to find the answers. A research gap is exactly how Dr. Tina Lasisi, interviewed for the Melaninology episode of the Ologies podcast , describes how she got into this field of research [starting around 6:22]: I…
The next time you’re in a meeting, wishing you weren’t, you might want to consider why the meeting feels so insufferable. Often it’s because no one has bothered to consider the purpose of the meeting. Cam Daigle devised a classification system that provides an excellent framework for improving meetings. They declare that There are three types of meetings : I believe all meetings…
As a technical writer, I have a mixed opinion of chat applications like Discord and Slack. On the one hand, they make it easy to quickly get ahold of someone who can answer your questions, which is a relief if you’re struggling to gather information you need to write a draft. On the other hand, because it’s easy to quickly get ahold of someone who can answer your questions, that…
Gwen Windflower asks Are you actually measuring data quality? : Data is a woven net thrown over the world, capturing it in a grid of variable resolution. We want to capture as much detail as we possibly can, but it’s then crucial to make judicious decisions about how we translate what we capture into a useful map. Documentation involves a similar discernment process as data analysis and data…
In 2022, I had no true “obsessions” in my music listening, unlike last year. Instead of any standout artists, I flitted from artist to artist as they released new albums or other things prompted me to rediscover how much I enjoyed their music. This was a year for breadth, rather than depth, and also for discovering the limits of my music data collection mechanisms. If you want to skip…
It’s time for another deep dive into this year’s Spotify Wrapped! I’ve been doing this for almost as long as Spotify Wrapped has existed. Check out the past years’ posts: 2018 , 2019 , 2020 , 2021 . I collect my music data using Last.fm , and then I wrote a custom Last.fm add-on for Splunk to send my listening data to Splunk . I then use the app I developed, Music App for…
It’s tough to find helpful information about analyzing website metrics for technical documentation sites. The goals of technical documentation are different from those of a marketing blog or a company website. You’re not optimizing for maximum traffic. No one is clicking “Add to Cart” on your API reference topics. You need to use slightly different metrics and in different…
Image generation tools like DALL-E 2 , Midjourney or interfaces built on top of Stable Diffusion have gained a lot of popularity, both due to the quality of images created and the novelty of transforming text input into a visual output. The other aspect of their popularity is that these tools let people without art or design training use text to describe what they want to see, and then (hopefully)…
If you’re writing documentation for a software-as-a-service (SaaS) product that releases constantly, it’s easy to be overwhelmed by the amount of new functionality being released that needs to be documented. But do you really need to document all of it? Nope. Instead, document the hidden, document the weird, and document the why. Consider every new product feature in terms of what the…
Matt Webb wrote a post about organizing data and mapping the experience of the web, and that made me consider how the decisions about documentation structure, especially in the early stages, require similar decisions. Technical documentation functions as a map for your product. For specific users, your documentation provides wayfinding guidance and provides the information necessary to navigate…
I’ve frequently seen product thinking discussed in product management and user experience design contexts, but haven’t seen it applied to technical writing and documentation. And yet, by applying product thinking to documentation, we can write more useful, relevant, high quality documentation. What is product thinking? Product management thought leader Shreyas Doshi defines product…
It’s been another unexpected year. Thinking about how I had a January and February stacked up the same way I spent all of my 2019, and booked up an April 2020 to be more of the same, and then whomp, pandemic, and all of my priorities changed. I’m back with my yearly music data rundown, featuring a comparison with my Spotify Wrapped data (as always), a deep dive into my artist obsession…
I’ve been listening to the Farnam Street podcast, The Knowledge Project , recently and enjoying the guests that have talked about The Personal MBA or Relationships vs Transactions . But I noticed a pattern. I realized that the guests were largely telling stories about men, mentioning books by men, and I didn’t see myself in these conversations. When I went to dig deeper into the…
More and more startups and enterprises are recognizing the importance of high quality product documentation, but it’s tough to know where to start. I’ve taken a few enterprise software products from “nothing to something” documentation and this is the framework I’ve built for myself to create MVD—minimum viable documentation. If you’re a technical writer trying…
As a professional writer, I frequently get asked, “as a ______, how can I get better at writing?” I’ve never had a good list of resources to point people to, so I finally decided to write one. I’ve worked hard to become a good writer, and I’ve had the privilege of many good teachers along the way. If you’re not really sure why your writing isn’t as good as…
Another year, another Spotify Wrapped campaign, another effort to analyze the music data that I collect and compare it to what Spotify produces. This year I have last.fm listening habit data, concert attendance and ticket purchase data, livestream view activity data, my SoundCloud 2020 Playback playlist, and the tracks on my Spotify top 100 songs of 2020 playlist . It’s always important to point…
This is the eighth and final post in a series about how missing data biases data-driven decisions. Start at the beginning: What’s missing? Reduce bias by addressing data gaps in your analysis process . In this post, I’ll cover the following: Define the question you want to answer for your data analysis process How does data go missing when you’re defining your question? What can you do about…
This is the seventh post in a series about how missing data biases data-driven decisions. Start at the beginning: What’s missing? Reduce bias by addressing data gaps in your analysis process . When you’re gathering the data you need and creating datasets that don’t exist yet, you’re in the midst of the data collection stage. Data can easily go missing when you’re collecting it! In this post, I’ll…
This is the sixth post in a series about how missing data biases data-driven decisions. Start at the beginning: What’s missing? Reduce bias by addressing data gaps in your analysis process . In this post, I’ll cover the following: What is data management? How does data go missing, featuring examples of disappearing data What you can do about missing data How you manage data in order to prepare it…