Grab a comfy seat and a hot cup of joe, because it’s time for some coffee talk with Nick & KBall! Special guest Thomas Eckert joins the party and brings a bunch of questions for us to discuss.
Who wins in a fist fight: Tailwind CSS people or “real” CSS people? Is Agile overrated? What’s the longest bug you’ve ever chased? How about some underrated libraries/packages that people should know about? And more!
Congrats to Dan, Rachel and the entire React team for shipping a new docs site! Here’s their TLDR:
In a world where most documentation sucks, large language models write better than humans, and people won’t be bothered to type full sentences with actual punctuation.
Two men… against all odds… join an award-worthy podcast… hosted by a coin-operated, singing code monkey (?)… to convince the developer world they’re doing it ALL wrong.
Grab your code-generator and heat up that cold cup of coffee on your desk. Because this episode of Go Time is about to blow your docs off!
Shahed Nasser shares how she and the technical writing team at Medusa went about improving their docs:
The most essential change that helped us implement all improvements is how we manage the documentation. In most software companies, documentation has less of a priority compared to the software, and it is handled as an afterthought.
At Medusa, we early on came to realize that documentation is what can actually drive further adoption of Medusa.
There’s a lot to learn from their process that you can apply to your own, but I think the biggest winner Shahed shares is the mindset change of thinking about documentation itself as a product, not as something that augments or attaches to the product.
Kate Monica and the team at Tremendous have been doing this high-documentation, low-meeting work culture for awhile now, so she wrote up five discrete benefits that they’ve seen as a result of it.
Docusaurus maintainer Sébastien Lorber joins Jerod & Amal for a deep-dive on everybody’s favorite documentation generator. It’s back with a big 2.0 release, boasts some big users, and has a big set of new features such as document versioning, a plugin architecture, and more.
Meta just released a stable version of their new documentation static-site-generator, after a 4 years alpha/beta period. It allows you to focus on content and just write Markdown files. Based on Node.js, React and MDX. Powering many docs sites including React-Native, Supabase, Redux, Tauri, Electron, Courier, Ionic, Figma, Prettier, Babel…
I’ve long been fascinated by literate programming (the art of writing code as if it was a novel), but it’s been awhile since I’ve seen a good example of in practice. Here’s a good one:
I wanted to showcase the BDD-inspired low-tech solution I came up with via a toy project, demonstrating a small but significant programming task, broken down as series of design-implementation cycles.
Wordle is a perfect target: it’s a small codebase, with a half dozen features to string together into a useable game.
This story has five chapters and a satisfying conclusion:
This project was my first foray into literate programming at this scale, an attempt to bring together all the good ideas of TDD, modern Python development, Gherkin usage for requirements traceability purposes (without overly zealous extremes of Cucumber automation). All these ideas were until now scattered, implemented each without the others in different places, and this project fuses them into something I hope is more valuable than the sum of its parts.
Solid piece on literate programming by Richard Gall for The New Stack. My foremost exposure to the practice came from Jeremy Ashkenas’ CoffeeScript and Backbone.js docs. I always found it cool and useful to read, but couldn’t imagine myself writing code/docs that way. Which brings us to this bit at the end of the article:
“One of the things we learned is that it’s very expensive,” he said. “And so you spend time trying to figure out what sort of situations justify the expense. And one of them is where people are building relatively small, sophisticated kernels that are going to be shared widely.”
Seems like Jeremy’s use case drilled it. If you’re mostly writing application code, literate programming probably isn’t worth the headache, but for library/framework authors…
Rachel Nabors –beloved educator, animator, & documentation engineer at Meta– joins Amal and Amelia for a first look at the brand new React docs!
This massive overhaul to the React website (which supports 2 million+ developers around the world) was no easy feat! We dive into all the behind the scenes coordination, as well as the goals, wins, and intended outcomes of this new way of approaching educational content and API reference material for open source projects.
git-cliff can generate changelog files from the Git history by utilizing conventional commits as well as regex-powered custom parsers. The changelog template can be customized with a configuration file to match the desired format.
On this week’s episode, Gerhard is joined by Kathy Korevec, former Senior Director of Product at GitHub, and now Vercel’s Head of Product. Docs play an essential role in GitHub Actions, and Gerhard’s experience has proven that. Building, testing, and shipping code with GitHub Actions works better because of their excellent docs. However, the docs that Kathy pictures are not what you are imagining. She explains it best in her post, Maybe it’s time we re-think docs, which is what started this whole conversation.
The bottom line is, just as you wouldn’t ship untested code, shipping code without documentation is not optional. Today’s conversation with Kathy explains why.
Kathy Korevec has been putting a lot of thought into documentation as part of her work at GitHub:
Wouldn’t it be great if the docs knew that you were writing a Python app on a Windows machine and that you preferred watching videos instead of reading through text? I want you to find the answer to your questions in the docs, easily and efficiently. When you’re stuck on a problem and you turn to the docs, there’s a moment of magic as you find the solution, try it out and it works. In that moment you become unblocked, you learn something new and you can move on to keep building your application.
In this post, she outlines 10 guiding principles she developed after speaking with hundreds of developers about their struggles with documentation. She then shares how she’s putting those principles into action in/around GitHub. Good stuff.
Porter lets you package your application artifacts, client tools, configuration and deployment logic together as a versioned bundle that you can distribute, and then install with a single command. Written entirely in Go, we speak to one of the creators about running an open source project, the importance of documentation, and more.
The week we talk about the new Open Web Docs initiative and the future of MDN.
Documentation. You can treat it as a dictionary or reference manual that you look up things in when you get stuck during your day-to-day work OR (and this is where things get interesting) you can immerse yourself in a subject, domain, or technology by deeply and purposefully consuming its manuals cover-to-cover to develop expertise, not just passing familiarity.
In this episode we pull in perspectives and anecdotes from beginners and veterans alike to understand the impact of RTFM deeply. Also Sweet Filepath O’ Mine?!?!
If you maintain an open-source project in the range of 10k-200k lines of code, I strongly encourage you to add an ARCHITECTURE document next to README and CONTRIBUTING. Before going into the details of why and how, I want to emphasize that this is not another “docs are good, write more docs” advice. I am pretty sloppy about documentation, and, eg, I often use just “simplify” as a commit message. Nonetheless, I feel strongly about the issue, even to the point of pestering you:-)
The author points to rust-analyzer as a good example.
I dig this effort to decouple web documentation from a “single vendor or organization.” 👏
Open Web Docs was created to ensure the long-term health of web platform documentation on de facto standard resources like MDN Web Docs, independently of any single vendor or organization. Through full-time staff, community management, and our network of partner organizations, we enable these resources to better maintain and sustain documentation of core web platform technologies. Rather than create new documentation sites, Open Web Docs is committed to improving existing platforms through our contributions.
Wanna get involved? Check out the high-level goals they have laid out.
GitHub open sourced this long-lived private project. Learn about the why and how in this post…
Last week we open sourced all of GitHub’s product documentation, along with the Node.js web application that powers it. Check out our new public repository at github.com/github/docs.
This post tells the story of why we wanted to open source the docs, what tools we built and open sourced along the way, and how we worked to make the project welcoming to external contributors.
Rina Jensen shares more details on the future of MDN Web Docs in this post on Mozilla Hacks.
First we want to be clear, MDN is not going away. The core engineering team will continue to run the MDN site and Mozilla will continue to develop the platform.
However, because of Mozilla’s restructuring, we have had to scale back our overall investment in developer outreach, including MDN. Our Co-Founder and CEO Mitchell Baker outlines the reasons why here. As a result, we will be pausing support for DevRel sponsorship, Hacks blog and Tech Speakers. The other areas we have had to scale back on staffing and programs include: Mozilla developer programs, developer events and advocacy, and our MDN tech writing.
Have you heard of the GitHub Arctic Code Vault? If not, the goal of GitHub Arctic Code Vault is to preserve open source software for future generations. Which means we need thorough docs describing how the world makes and uses software. Which I find completely fascinating!
From the GitHub Archive Program readme:
We are now also opening up the initial compilation of Tech Tree resources to community input. Inspired by the Long Now Foundation’s Manual for Civilization, the Tech Tree is a collection of technical works which document and explain the layers of technology on which today’s open-source software relies, along with works included to provide additional cultural context for the Arctic Code Vault.
What follows, which we call the Tech Tree, is a selection of works intended to describe how the world makes and uses software today, as well as an overview of how computers work and the foundational technologies required to make and use computers. The purpose of the GitHub Archive Program is to preserve open source software for future generations. This implies also preserving the knowledge of other technologies on which open-source software runs, along with a depiction of the open-source movement which brought this software into being.
1️⃣ Value contributions to documentation just as much as code contributions
2️⃣ Put documentation and code in the same project repo
3️⃣ Make documentation a requirement for a merge or release milestone
4️⃣ Have a consistent contribution process for code and documentation
5️⃣ Have well-documented processes for contributing to documentation
That’s the TL;DR, but each of these is expanded upon in the article.
Looks interesting. Would you use this?
Searches a curated subset of the web: official docs and community-driven sources. No JS, cookies, tracking, external requests or data collecting.
There’s lots of feedback from Rakhim (the creator) and commentary on Lobsters too.
Are you striving to create a culture of written comms? Maarten Claes writes…
More and more people are being exposed to working remotely. One of the key factors for success in a remote workplace is a culture of written communication. It’s not always obvious how to create such a culture, and it takes at least some level of discipline from the people involved to make it a habit.
I’ve worked with mostly remote teams over the past three years. Here are a few of my observations on what helped cultivate such a culture.
David Thompson:
I like Git commit messages. Used well, I think they’re one of the most powerful tools available to document a codebase over its lifetime. I’d like to illustrate that by showing you my favourite ever Git commit.
6-ish paragraphs of explanation for a single whitespace change in the code.
