Author's notes – How this project is maintained

[squidfunk]

Maintaining a project of this size is hard. This is an attempt to explain the rationale behind the decisions when triaging issues, considering features for implementation, and merging bug fixes.

Templates – the most opinionated projects

There is probably nothing more opinionated than a template. Material for MkDocs is exactly that – a bunch of Jinja 2 templates and partials that are rendered by MkDocs to form beautiful HTML pages with some CSS and JavaScript sprinkled on-top of that. Those very sprinkles are what make this project so compelling to use – all features are implemented with a focus on usability (user experience and developer/author experience), accessibility, mobile-friendliness, and of course customizability. Furthermore, this project will generate a beautiful and functional static site – hosting technical documentation couldn't be cheaper or simpler.

A great template takes a lot of the boilerplate and pain away by providing sane defaults, as well as best-practices to authors while retaining maximum flexibility. HTML, CSS, and JavaScript are languages that allow for amazing interoperability. Choose some third-party JavaScript library (like Mermaid), add a little glue code, and get going! HTML is, after all, the dream of modularity and interop coming true, which I believe to be one of the crucial success factors of the modern web as we know it.

Templates are blueprints. In the majority of cases, Material for MkDocs should check a lot of the requirements when building technical documentation. If it doesn't, you might be better off with another solution, as there are many to choose from in the documentation space. However, companies come in all shapes and sizes and have different requirements, thus to achieve the last 5-10% in order to refine this template to fit your brand's CI, some customization might be necessary. This is an irreducible problem, because of the sheer versatility of use cases, which cannot be solved by adding more and more configuration flags and switches into the templates.

A day in the life of a maintainer

After five years, the core maintainer of this project is still a single person: @squidfunk, i.e. me. While there have been several great community contributions, more than 90% of the work on this project is done by me. There's a very interesting paper called "The Impact of Heroes on Software Development". According to the terminology of the paper, a project is driven by "hero developers" when 80% of the contributions come from less than 20% of the developers. Although I wouldn't call myself a hero, this ratio does hold for this project.

One explanation for this ratio might be user demographics. In 2020, we did a survey to learn about demographics, user happiness, and possible directions to explore with this project. The results were released on Twitter and yielded interesting insights. In fact, only a very small percentage (< 10%) of the users of Material for MkDocs actually would consider themselves frontend engineers. Thus, most users are not overly experienced with CSS and JavaScript but feel comfortable making small adjustments to customize the look and feel. Material for MkDocs makes this very easy, explaining how to hook into the theme or change the overall appearance with a few lines of CSS as part of the official documentation.

Another possible explanation is the complexity of this project. When adding a new feature or changing the behavior of an existing one, the following things have to be considered:

• The new feature is not incompatible with one of the existing features
• The new feature can (ideally) be used together with all existing features
• The new feature can be implemented in a way that it is accessible
• The implementation follows the principle of progressive enhancement
• The implementation works on all screen sizes (mobile, tablet, desktop)
• The implementation works on all modern browsers (nope, not IE)

When evaluating a feature or pull request, all of these points are considered forming a decision whether it is worth pursuing. Even if all of these boxes can be ticked, there're additional requirements that weigh into the decision:

• The new feature can be implemented with reasonable effort
• The new feature matches the overall "tone" of this project
• The new feature is useful to the majority of users
• The new feature is easy to use for authors

If a feature or pull request cannot tick all of those boxes, I always try to pinpoint and explain what might be problematic in terms of implementation. As with all of us, my time is limited, so sometimes answers might be brief and link to related issues or discussions, trying to provide additional context. Sometimes, it's just not feasible to explain that a seemingly trivial feature request is simply not economical to implement because one or some of the boxes listed above can't be ticked. Furthermore, when a feature can be implemented with some extra lines of CSS or JavaScript, I try to either provide a prototypical implementation ("this can be achieved with a few lines of CSS ..."), point to the relevant files or articles that explain how it might be achieved with the powers of HTML, CSS, and JavaScript.

The official documentation contains a long section on customization, which explains how to make changes to templates/partials, add additional CSS and JavaScript, and outlines several theme extension strategies (overriding blocks, partials, or forking the theme) to achieve exactly what you want. Material for MkDocs follows semantic versioning as much as possible, trying to reduce breaking changes to major versions. Furthermore, all template changes between major versions are documented in the upgrade guide.

I always try to keep open issues and pull requests to a minimum, not exceeding an amount of 10-20. If you look at other Open Source projects you will see that there are piles of open issues, stacking up to hundreds and sometimes thousands. Losing control/track can happen fast, gaining it back or keeping it can be exceptionally hard.

What Sponsorships achieve

In May 2020, I decided that it's time to try something different. After years of work on this project, sometimes taking weeks of my time, I asked myself whether it would be possible to make this project sustainable. To achieve this, I would have to make sure that I have sufficient resources to address feature requests and bug reports and keep this project and its codebase in good shape. The most important resource in the developer world is, of course, time, which for most of us in the human world equals money. GitHub Sponsors seemed like a good fit.

Today, I'm regarding the Insiders program as a hugely successful experiment. Providing an incentive to sponsor, giving early access to the newest features of Material for MkDocs, more than 100 users are already paying $ 10 or more a month. This currently sums up to more than $ 1,600 MRR, which I never thought would be possible to earn with something like a template. However, while $ 1,600 a month may sound like a reasonable amount, in the tech world, it's actually not that much. In fact, after exchange rates and VAT, it's less than I earn as a freelancer or consultant in a single day. However, each commit to this project yields infinitely more value than working on a client project, providing value for a single customer. I really want to make this project sustainable, which is why I'm working so hard and investing so much time into it, and hope that we can increase this amount in the coming months (and years). This will ensure that at some point when I'm not capable of maintaining it anymore, there's enough MRR to pay somebody talented to do it for us.

Closing thoughts

I hope that this post could shed some light on how this project is maintained and some of the decisions that I made in the past. If one of your feature or pull requests got turned down, I'm sorry for that. Maybe you can reconsider and understand why this happened after reading this post. In case you have any questions, please don't hesitate to ask!

[squidfunk]

Yep, I got an invitation to the @abandonware organization, but why? Makes no sense to me.

[rzr]

In case " when I'm not capable of maintaining it anymore,"

[facelessuser]

If that happens, can't someone just fork it and add it? I'm not sure why anyone would transfer ownership of a currently maintained project.

[facelessuser]

Or contact the author once it becomes abandoned and see if they want to transfer it?

[squidfunk]

I think @rzr refers to:

This will ensure that at some point when I'm not capable of maintaining it anymore, there's enough MRR to pay somebody talented to do it for us.

The sentence states, that at some point in the future when I, the author of this project, can't afford the time to maintain it anymore, we'll want to make sure there are enough sponsorships to pay somebody to do it, so this project is self-sustaining. We're on a good track. Currently, this project is very active (see the commit history) and there's no plan to abandon it.