How does Boiling Steam work behind the scenes? No, I’m not talking about the CMS (Content Management System) we use (Wordpress), because that would be a rather boring topic in itself… Rather, how does the small team behind our publication actually organize itself? And what tools do we use?

The Key Setup: Offline First

Boiling Steam is a team of 4 contributors currently (Patola, Podiki, Cow_Killer and myself, Eki), and we so happen to be working in very different locations and time zones (from the US to Japan - making our time online together rather limited). So everything we do has to assume other members are potentially offline or not available - so we adopt an ASYNC mindset: we work in parallel as much as possible and reduce sequential operations to the minimum.

Of course, we still have some time online every single day, and we need a communication tool to chat and interact. We do have each other’s emails but we rarely use it for communication. Instead… we use Matrix.

Communication: Matrix/Element

The amount of tools for chatting online is staggering these days. Great amount of choice, even if you only want to use FOSS tools. In our case we have settled on Matrix (and Element as a client, but there are many others) for the following:

• FOSS solution
• Could be completely decentralized if we ever wish to (self hosting) - for example Podiki joins us on Matrix from his own self-hosted Matrix server, and you can see that from his username being on his domain. He mentioned that in an article he wrote for Vice not too long ago.
• End to End encryption
• Works well on Desktop and Mobile (iOS and Android)
• Makes it possible to do audio/video calls too. (powered by the Jitsi integration)

Also, we are generally quite happy with how it works: not too many issues (videoconferending is not perfect though) and this is really helpful to leave some messages when some of us goes to bed while the others still have a good half day ahead of them.

That’s fine for casual chat and info sharing, but when it comes to coordinating articles, we have settled on a git repository, and the web app Gitea to manage it, as our main system. We also self-host Gitea (it’s very simple to deploy!) on one of our servers for additional flexibility. As you see we don’t just talk about FOSS, we also actively make use of it :)

Podiki has also a separate self-hosted Gitea instance where he mirrors our main server’s git, as a backup in case things go wrong. We have been working with this for a fairly long time now, and this system has proven very robust.

Enter Gitea: Git Repository, Issue Tracking and Overall Management

Gitea is, to put it simply, an app made to access, modify and manage a git repository through a web interface. You should be using it mostly for code versionning, but it also works for managing a publication. Let us see in more details how we use it:

Everything is done in Markdown

To leverage a code versioning tool which relies on text and lines like Git, we adopted a standard across all of draft articles: they need to written in Markdown (if you are not familiar with Markdown, it’s a very simple markup format which uses visual cues to mark text up). Markdown is largely sufficient for blogging and there is virtually no need to go beyond that. The other advantage is that everyone can use their preferred text editor as well. I do everything in Vim (with the Goyo plugin) for example, while Podiki likes to do everything in Emacs (his documents are actually .org files, but they render just fine as well on Gitea’s web interface, it’s in any case still text). Cow_killer likes to use the text editor included in the Gitea interface: at the end of the day it does not matter as format is always, always text.

Every change can easily be tracked

Because we use git as a central system, all changes to every article are clearly tracked to whoever did them and what they modified. Since git manages changes at the ‘line’ level, a long paragraph in text is usually considered as a single line. So changing a typo somewhere in the paragraph would show that the whole paragraph has been replaced instead of just the typo itself. This is were git is not ideal for text editing as code and text follow different conventions (code lines tend to be short). But it’s not as bad as you might think. When you have a very long article anyway, just looking at the history tab and focusing on the few paragraphs that changed is still a very effective way to review the improvements.

You can see that Gitea’s web interface for history will highlight within the changed paragraph has been added with a different shade of green. Very practical.

Every new article is a branch

If you are familiar with git, you know that there is a master branch which keeps the current version of the repository, and collaborators typically use branches to implement new features or bug fixes. We do the same thing, except that we work with articles. Branches make it possible for us to make a clean separation between what’s ready to be published and what still needs work, reviewing or polishing.

Once we are all happy with how an article shaped up, we then merge it into the master branch.

Every new article is an issue

At the same time as we create a new branch for articles, we typically create a new issue in Gitea too. Issues are usually there for bug reports or bug tracking purposes. We use them to track what articles are currently in progress. Issues have their own discussion threads, so it’s very practical for us to exchange thoughts, ideas, and feedback on what we write about. This also touches on something very fundamental to how we work: Peer Review.

Peer Review Process

Boiling Steam typically focuses on longer features, reviews, guides, less so on news. We do cover some news that we consider very relevant, but most of the time if you want news you should subscribe to our Mastodon or Twitter feeds instead - this is where we share them. On the site, we all enjoy doing these bigger pieces and spending time getting it as good as we can.

The Peer Review process helps avoiding numerous pitfalls related to every topic we write about, and is also a way to validate that each article is at least insightful to read. You can ask all of us and I think we all agree that all of our articles benefit a lot from the additional points of view: I can’t think of a case where it did not help or did not bring any improvement.

To give you a couple of examples:

• For the recent Max Payne 3 article, I had completely skipped a proper introduction to the series, assuming that most people would be familiar with Max Payne already. Turns out that this is far from being the case, and new generations of gamers are much less likely to have heard about it. So I added a lot of background details and explained the mechanics of the series in more depth.
• For Podiki’s Move to AMD article the initial draft sparked a lot of questions from us Nvidia users, and resulted in more testing, more confirmations, and more details on how to do the actual transition on an established system.

Doing Peer Review also works well because we all have different backgrounds, tastes and experiences. If we were all from the same mold, it would not be nearly as helpful, nor let us reach beyond an audience we know individually.

Peer Review should not be considered a silver bullet. It will not magically make all errors disappear or render every article perfect. But the more we have feedback, the more we can fix our individual blind spots, so the articles you end up reading are much more robust than their very first draft.

There is no set period for Peer Review: it can take a few days to a few weeks, in case the article demands it. I would say that on average it takes 4-5 days between several rows of feedbacks and a final version. It’s definitely taking more time to follow such a process rather than just writing and pushing articles as soon as we have a draft ready.

How do we deal with the fact that articles may take longer to finalize because of them? Well, we ensure we have a constant stream of new potential articles that we are working on: as long as we work on parallel on several of them, we will be able to release a few articles every week, statistically.

Issues live on the Kanban

We used the track the status of all articles on a Markdown file, between Ideas, Drafts in Progress, Drafts Under Review, and Articles To be Published categories. It was OK, but last year Gitea has finally introduced a Kanban view to manage issues visually just like you could do it on Trello, for example, or many other systems focused on Agile development.

This has made it easier to link our Issue threads to an overall status, and we can therefore have better control as to what we plan to publish on a weekly basis.

Alerts

While most of the process relies on manual tasks, we have a few automated alerts to make sure we do not waste time either. Not everyone is logged in the Gitea at all times (we all have our other occupations after all), but we do have an alert system that sends an email every single time a change occurs on the git repository. If I was waiting for Cow_killer to update his article, as soon as I get the email notification I can go back to Gitea and check what’s happening. In practice, I’m not that fast, but at least I know it’s pending.

How do such alerts work? Well, we also have a Jenkins instance. Jenkins is a Python piece of software that is usually used for CI/CD - it’s made to interface well with code repositories, so I use it to watch the repository using webhooks, and when changes happen it triggers a Jenkins workflow that will pull some relevant info and send it to everyone by email. Nothing too fancy, but very practical at the end of the day.

Transparency

One of the other aspects of doing everything through a git repository is that everything is completely transparent. Everyone can see the whole discussion, the edits, and comment on what is happening. There is no hidden authority, no secret trade-offs: the whole history is open to everyone in the Boiling Steam editorial team, and changes are justified by a clear reason.

To me the transparency aspect is almost as important as the operational process: I would not have it any other way.

The future

We are always thinking on how we can improve our ways of working:

• Any new tool we can use?
• A way to better communicate?
• Some more things we could self-host that make sense?

We don’t necessarily make changes on a weekly basis, but come back in one year and there’s certainly some aspects that will have evolved and improved. As as our team keeps growing, we will face new needs and we will certainly have to review again how to best achieve our goals, to serve the Linux gaming community.