brson's writings

I enjoy writing, and sometimes think I’m pretty ok at it. Like my code, I like my words to be a mixture of engineering and art. It tends to be an arduous process, so I don’t produce much, but here are some of the pieces I’ve written.

  • The Minimally-nice Open Source Software Maintainer. This is the most fully-realized thing I’ve written, a piece about how to treat your contributors with respect, in a format inspired by “How to Win Friends and Influence People”. I like it because it is a mix of personal and professional subject matter, and in a unique voice. I worked on it for over a year.

  • Rust Compile-time Adventures with TiKV (series):

    One of the first tasks PingCAP gave me was to improve TiKV compile times. Then they asked me to write a blog post about it. The first draft I wrote was expansive, so I split it into 10 parts. Then the first part grew too large, so I split that in 2, then in 3, etc. So these four parts are, like, parts 1-4 of part 1 of 10. I’ll definitely never finish the rest.

    It took me about 7 months to complete the first of the series. In it, I purposefully used strong, colorful language, and a provocative title (though through edits I did tone it down considerably). After it was posted, the first comment about it was “I hate the delivery, but appreciate the insight”. Still learning from that, and I still haven’t read the HN comments about parts 2+. Every one did hit the HN front page though, so PingCAP was happy.

    The long editing process, and splitting it into so many distinct parts, I think made the total work really suffer. I have negative feelings about most of my work products, but I really hate this one. Also though I am proud that I finished it, at least these four partrs.

  • Fireflowers: The Rust programming language in the words of its practitioners. A project to capture a particular moment in time for the purpose of marketing, while celebrating the Rust community. I was proud that I was able to put this simple concept together in a single weekend. I also remain satisfied with the visual design, though some felt the colors were eyeball-searing.

  • Reddit-flavored Markdown v2. I was responsible for finalizing the implementation of the Markdown Parser for Reddit’s 2018 redesign (which was itself a fork of comrak). This is the public portion of the giant braindump I left in my wake.

  • Practical Networked Applications in Rust. A course on building real-world applications in Rust. Developed for PingCAP as a recruiting tool. Incomplete, but I have ambitious hopes for it.

  • Experience report — first time running and building CKB. A type of writing I do a lot — attempt to do something new and write down everything that happens.

  • Refactoring std for Ultimate Portability. A proposal for how to refactor the standard library into portable components. I like how complete the argument is here and that I took the time to make illustrations.

  • How Rust is tested. A comprehensive report on one of my favorite subjects.

  • The rustup readme. It’s pretty comprehensive and well organized. I’m sure others have modified it since, but I wrote most of it.

  • Future updates to the rustup distribution format. A description of how the rustup infrastructure and protocol works.

  • Starting a new Rust project right, with error-chain. A simple instruction on using the error-chain crate. I like this one because I wrote it in an afternoon, where most of my writing takes much longer.

  • The End of Unsafety. A presentation I gave with Alex Crichton. The repo contains a complete script, for my parts at least. I was quite satisfied with the theme, aesthetics, and attention to detail in the deck, particularly the animated “balloon borrowing” demonstration.

  • An annotation of the Rust standard library. This was a small project to illustrate some of the neat little mysteries and hacks employed by the standard library. I like it mostly because it uses the GitHub pull request review as the medium.

  • The “North Star” RFC. I mostly stay away from the RFC process because the open debate is unpleasant to me, but this is one of the better I’ve written. It lays out a process for establishing the Rust roadmap. Our actual conformance to the process established therein ended up being quite low.

  • Redesigning the Rust runtime. Back when Rust had green threading and the runtime was written in Rust, this was my plan to rewrite it in Rust, which I subsequently did with Ben Blum. In retrospect I didn’t know much about building thread schedulers, but I still saw the runtime through two rewrites, and it all worked. All that code is long gone now though.

  • Abandoning segmented stacks in Rust. This was the moment that Rust began its shift away from green threading to native threading. At the time we naively hoped we could still do green threading by having the OS map stack pages lazily, but nope. Bye, bye, green threads.

  • The Rust Libz Blitz. A blog post announcing a major project I was responsible for. I was extremely unsatisfied with how this came out, and basically gave up and had others edit it to completion.

  • Let’s make a web service and client in Rust. This uses the awesomely powerful technique of doing a thing, and writing it down as you go so that others can learn from it.

  • Perfecting Rust Packaging. Not amazing writing, but this was the announcement of a major cross-project coordination effort. I like the title.

  • Announcing Rust 1.15.1. This is mostly interesting because of the community management aspect. The 1.15 release had a glaring soundness bug, and this is the mea culpa. The resulting 1.15.1 release itself was difficult, and resulted in a post mortem.

  • Rust CI / release infrastructure changes. Just technical communication about CI.

  • How the Rust issue tracker works. A modest exposé of tribal knowledge.

  • The Rust Standard Library. I wrote the crate-level documentation for the standard library, that is, the stuff that is on the landing page. This is a link to 1.18, which is current as of mid-2017. It could use a refresh, and I’m surprised it’s lasted as long as it has.

  • The Rust compiler 0.1 is unleashed. An announcement of the first release of Rust, in 2012. It’s small, but I’m proud that I got to make that announcement. I’m also proud of the second paragraph, that explains what Rust is, a simple thing that many release announcements omit. I’m good at anticipating important details like that. I also remain tickled that I got away with writing “unleashed” in the title. That would not fly today.

  • prev.rust-lang.org. I’m responsible for a large amount of the content on the Rust website (as of 2017), including the (increasingly outdated) contribution guides, the install pages, and the long-standing tagline, “Rust is a systems programming language that runs blazingly fast, prevents segfaults, and guarantees thread safety”. I also am largely responsible for the visual design, which admittedly is highly-derivitive of stock bootstrap, but I’m quite proud of my aesthetic sense, and ability to work within my own limitations. Plenty of people have criticised the Rust website over the years, but it does what it needs to pretty well. Ask me about my feels re the current Rust website.

  • A Rust Syntax Guide. I forgot that I wrote this gist, then one day in 2020 I discovered it had 27 stars on GitHub. It was delightful rediscovering this little thing that I did.