I was the chief editor for this blog for the past 8 years or so, and I’ve just recently passed the mantle to Chris Harrison. I thought I’d take the opportunity to write a little bit about this blog, how it’s operated and what it means to us. Besides, we do like when things get meta here, so this is a blog post about the blog.

A little bit of history

One of the tenets under which Mathieu Boespflug founded Tweag was that software engineers naturally don’t write enough. Writing is an essential part of the engineering job. We write issues, pull requests, code comments, documentation of various sorts. We discuss and debate online, we have to arbitrate trade-offs. Most of this is common, in fact, to every engineering profession. And although we typically become engineers because of our taste for the technical part of our job (I certainly did, I don’t know for sure how ubiquitous it is); writing is still a big part of our job.

So Mathieu reasoned, if writing is to be such a big part of our job, but we’re technical people at heart, not writers, for the company to be at its best it needs to make it clear that precise and clear writing is important to our job. To that effect, there ought to be venues for us to write, where it was made an expectation, an actual requirement, for us to write. The blog is one of them.

At first, the blog was just there. After all, our blog was, and still is, just (part of) a Github repository. So we’d make pull requests and merge blog posts. But, of course, people seek review. When you’re posting in the name of a company, you tend to be a little more careful about what you write; besides, we’re all so used to having our PRs reviewed. This was all very ad hoc, there was no process for it.

Whatever my reason at the time (I honestly don’t remember after all this time), I ended up participating in the review of most blog posts. It’s a poorly kept, but surprisingly little discussed secret that the most common way to get a responsibility in a company is to just assume said responsibility. Do the thing, and it will become your charge. Anyway, I became editor in chief.

Why we blog

Besides being a venue to exercise our technical writing, this blog has been tremendously useful to us. Keeping a high-quality, serious, technical blog helped establish trust in our work, build bridges with community, and attract clients and employees.

It’s very rewarding for us, as individuals, to be recognised by our peers, and to work with a company which is likewise recognised. This is certainly a great motivation for us to write.

Besides, it fits very well with our open-source values, both as a company and as individuals. We strongly believe in open-source, and the value it has to the world. So we participate. And open-source software isn’t just about putting software’s sources out there. Open-source is also about sharing knowledge. Which is another important element of the company’s ethos. We do have formal and informal venues for sharing knowledge internally, all very important stuff, but it’s a topic for another time. The blog is one of our main venues for sharing knowledge with the rest of the world.

So we do share, we talk about our open-source journey, the software we build, or the software we use. But we also share what we learn through working with clients, not necessarily on open-source projects.

So this blog is something that operates at the sweet spot of any company’s activities: it’s something we do because we believe that it’s the right thing to do, and it’s also something which is valuable to the company. In fact the blog brought so many clients that it allowed Tweag to operate without a marketing team for quite a few years. Nowadays, the company’s bigger and we can’t rely on a blog alone, but it’s still a great way to connect.

How we blog

Writing a blog post is making a pull request against the Github repository for the tweag.io website. A post is a Markdown file, possibly accompanied by resources (such as images). It’s a workflow which is very familiar to software engineers. All the review process is, in fact, a Github pull request review.

The author of a blog post is first tasked with obtaining a “technical review” from their peers: people close to the topic review the blog post for accuracy and relevance. The blog post editors are all engineers (the entire process, in fact, is owned by engineers), but aren’t necessarily very familiar with the blog post’s topic, so this first round of review couldn’t be performed by the editing team, it’s also much better for scalability as technical review uses a little time from a lot of people, rather than a lot of time from a few.

When the author and technical reviewers are satisfied with the blog post, they send it to the editing team, which will do two rounds of review (which we cleverly call “first editorial review” and “second editorial review”). The editing team reviews for clarity and writing quality. Something that isn’t a concern of reviewers (or really of the process as a whole), on the other hand, is SEO. Certainly our blog posts make our website easier to find, and of course this is important to us. But this is the result, we hope, of making blog posts that you like.

We can propose edits in three different ways: we can ask question in the review thread, propose “suggestions” in the Github interface which the author is free to accept or not, or we can push directly to the blog post (in which case we try our best to preserve the author’s voice, and always leave time for the author to check that the edits are correct). The choice between the three is primarily driven by our degree of confidence in the edit. Really we do what makes sense to reduce the amount of back-and-forth.

Reviewing blog posts on Github with a team distributed all around the world is essentially a distributed process. As with any distributed process, we try to minimise the amount of synchronisation. Our target is to be able to do a review in two weeks or less (one week for each round). Sometimes it takes more though, when the blog post presents more difficult editing challenges, or when the author doesn’t have enough availability outside of their client work to respond to our reviews quickly enough. But we hit the target more often than not.

The two rounds of review are functionally identical. We just found that, in practice, having two rounds of review helps raise the quality a lot. The first reviewer often gets involved deeply in the writing of the blog post, to the point that they stop seeing the blog post as a reader. The second reviewer receives a blog post in almost publishable condition and brings fresh eyes to conduct the finishing touch.

What blogging means to us

When Tweag was a standalone company, blogging was almost our entire marketing strategy. Now that we’re part of the substantially larger Modus Create, we aren’t in a position to rely solely on technical blogging for marketing. Yet, this blog is still an important part of our strategy.

All of what I wrote above still applies, but I’d like to bring up something else. See, a company is a little bit faceless. It doesn’t have a drive, it doesn’t have a personality: people do. This is truer the larger a company is. We don’t aspire to be a faceless abstract entity, though. Modus Create is made of people, people that we believe to be interesting, and that we hope you’ll find interesting too. In fact our business is largely for clients (maybe you!) to find our people interesting and hire us. This blog is one of the ways we use to promote individuals. Who they are, what they like, what they know, what they can do. This is why our writing recommendations encourage authors to use the pronoun “I” where many of us would be tempted to say “we”.

A more collectivist consideration is communities. We take part in a number of communities (Haskell, Nix, Bazel, Typescript, …), and it’s all too easy for a company to say it’s part of a community but really meaning that they just use Haskell, Nix, Bazel, Typescript. But it’s not really what being part of a community means, does it? It also entails taking part in community life. There’s a bunch of things we do: we write libraries, contribute upstream, help with governance, sponsor and sometimes organise events, …. And we blog, which also plays its part in community life. This is why we don’t shy away from highly specialised blog posts. Sure they are addressed to a pretty narrow, sometimes quite niche audience, but they are relevant to one of our communities. Of course it helps establish our technical chops. Hopefully it also builds trust.

I should note that what I’m writing about is what works for us. It’s not a recipe that will automatically work for you. There are many excellent technical blogs out there, which, I assume, probably have different approaches to us, such as CockroachDB’s, Netflix’s, fly.io’s and Trail of Bits’s (the latter two I wasn’t aware of, by the way, they were brought to my attention by this blog post’s technical review). If you like this blog, you’ll probably like theirs, go check them out! Dan Luu shares some more general considerations. But at the end of the day, what makes a strong communication strategy is to build around and empower the people you already have. Capitalise on your strengths, don’t go against the grain just to imitate what someone else does, however successful they appear to be.

Sign-off

A paradox of the work of software engineers (and probably all engineering disciplines really) is that writing is such an integral part of our job, but most of us receive virtually no training in our studies.

I’ve never had technical writing classes, myself. The way I learned writing was in part by gleaning some of the popular wisdom taught among my peers, but mostly by co-authoring scientific articles with better technical writers than me and seeing them do their magic. Honestly, I found no better learning experience than seeing an entire paragraph of mine rewritten in a mere few words that were also more precise.

I don’t know how to teach technical writing formally. So a lot of the process we’ve converged on reflects my attempt to replicate what worked on me for the company: teaching technical writing by example. By showing how a blog post can be improved, hopefully the authors will learn to write better next time. Because the blog is this as well: a tool to teach ourselves, collectively, how to be technical writers.

This is a very soft target, it’s hard to measure the degree to which we’ve succeeded. But, because I don’t really know how to close this post without getting a touch emotional (it is, after all, no small moment for me), I’ve witnessed many of our engineers mature as writers, and I can’t help but feeling some parent-like pride at their growth.