A Global Documentation Platform

I read A Global Design System by Big Medium’s, Brad Frost recently and it’s inspired thoughts that have been swimming around in my brain for quite a while: the precarious safety of web documentation. I think we’re sleepwalking into a disaster.

I want to start an earnest and serious conversation about how we, the web community, can fight back and preserve some of the most valuable content we need to do our jobs.

Mozilla: the organisation that can no longer be trusted permalink

I want to be absolutely clear that I wholeheartedly support MDN. I think it’s fantastic. I think it’s under the wrong stewardship though.

Let’s be frank: Mozilla is falling apart. Even as recently as this month, they have yet again, laid off staff in light of questionable strategic decisions. This time, it’s “AI”. Of course it is…

It’s not the first time though. Let me take you back to August 2020 when Mozilla unceremoniously laid off around 250 staff — a quarter of its workforce. This round of layoffs was to “focus more on products that generate revenue” such as a VPN. This was when I personally lost faith in Mozilla, the organisation.

Aside from the eye-watering number of staff laid off — in the thick of a global pandemic — the understandable community concern in this round was that most (if not all) of the MDN writers were laid off. Mozilla tried to reassure:

“The team is smaller, but the site exists and isn’t going away. We will be working with partners and community members to find the right ways to move it forward given our new structure at Mozilla.”

Community members did indeed step up and MDN has continued to get updates in the last 3 or so years. A big driver for this continued work on MDN is the folks at Open Web Docs. This is a fantastic concept and the team are some of the best in the business, but I personally worry when an organisation is mostly funded by Big Tech™ — currently Google, Microsoft Edge, Igalia and Canva.

It’s not that I’m necessarily anti-Big Tech™, but more, we can’t trust them. The last year or so has been plagued with often knee-jerk major rounds of layoffs, off the back of record profits (make it make sense). Who’s to say that these companies won’t also pull funding from community organisations like Open Web Docs too? Open Web Docs are fantastic, but they can’t survive that. The impact on an already thread-bare MDN contribution team would be devastating too.

What can we do? permalink

I think I’m going to get shouted at on the internet for this suggestion, but I think MDN core documentation content needs forking and an alternative platform needs to develop from that forked, attributed content that has a sustainable funding and leadership model. Mozilla ain’t providing that.

MDN has historically, been fantastic, but it is rapidly degrading, especially since they have integrated “AI”, which of course is massively flawed. Just read this thread of cursed examples. It feels like at an organisational level, there’s no drive for inspiring developers to learn and grow.

Something that is relevant to what I do specifically, both on this site and in general, is demos. Often, on MDN, demos are too abstract from real world use cases and frankly uninspiring. A good example of this is the examples on Using CSS animations.

Would they inspire someone to explore animation more? I think not. In fact, I’ve written about this before in the art of the demo. Mozilla could invest in this work — y’know, improving the docs so they help as many people as possible — but they instead introduce an “AI” helper that lies to people. Unforgivable.

The way I see it, if you mix a group of extremely technical writers and people that actually build stuff on the web together, the outcome will surely be great. I’m also likely slightly projecting here because I am not smart enough to read a spec, or even dry technical docs and understand them. My brain isn’t wired up that way. But, if there’s an interactive, inspiring demo, you bet I’m gonna soak up that knowledge like a sponge and I know I speak for many others who are similar to me.

The point I’m making is we as a collective can do so much better and importantly, look after an extremely valuable resource better. Something that’s focused on what it is, rather than something that’s good, but frequently gets enshittified by terrible leadership decisions.

The problem is, as exciting as it is to think about a better, global documentation platform, this stuff needs funding to do it right. Like I said before too, it needs a full time leadership team, which is in itself, a monumental challenge to put together.

Could this be something the Open Web Docs team lead on? I absolutely do not want to tell them what to do or pile pressure on them, but I also don’t want to undermine them by not including them in the conversation about a solution.

The onus shouldn’t be on individuals or corporate sponsorship for funding permalink

In community organisations the onus is often on generous individuals and corporate sponsors. I think the onus should be on companies that rely on web documentation for profit. Companies like mine, for example: a small agency that uses MDN on an almost daily basis.

Sure, if individuals want to support a movement like this, that is fantastic, but companies can wear the cost, along with benefitting from the cost in terms of tax liabilities. I personally wouldn’t think twice about an annual sponsorship for a global documentation platform via my company. It’s about giving back to platforms that give you so much as I see it.

Running a documentation service like MDN is expensive. For one, good technical writers rightly need paying good money for the value they bring. You need more than technical writers and editors though. You need project managers, designers, developers and research, just to name a few.

The thing is, there’s a wealth of people out there struggling to find work because Big Tech™ is laying them all off. It’d be a very good community thing if people in this situation could get paid for the wealth of talent they posses without fearing for their long-term livelihood.

Why do it like this instead of going all-in open source? permalink

It’s a valiant question but you don’t get documentation at level of quality of MDN with that model. You need stewardship from technical editors for a start. You also need a full time team of highly qualified writers to maintain and add documentation to the system.

A free-for-all open source approach would almost certainly result in high levels of contribution, but who manages that? Who maintains the quality? Open source is often lacking in equitability. I mean, there’s an XKCD for everything, right?

As I see it — and please remember this whole article is my opinion — a paid team of highly qualified people is the only route to a successful movement like this. The content should for sure be open to contributions, but the people that are responsible for its success need paying.

Open source is unfortunately treated as free, including lots of free labour. It’s free at the point of use, but people’s time and wellbeing is often exploited to achieve that.

Wrapping up permalink

I’m not even qualified to write this article, I just feel like it’s a conversation that needs to happen. Think of me as a rent-a-gob.

I’m just trying to start a conversation. I know that’s harder and harder now that communities have been fractured onto various social platforms, but y’know what hasn’t been fractured? Blogs. I’m calling on people to blog about this stuff and talk about it on podcasts. Heck, maybe in time, an organisation can grow from the ground up, like the increasingly successful Open Web Advocacy group who are successfully (and rightly) turning the screw on Apple’s anti-competitive behaviour.

MDN isn’t safe in Mozilla’s hands and the thought of it disappearing is terrifying. We can organise though and get something positive going before we have to because MDN has been rug-pulled. Fix the roof when it’s sunny and all that.

So to tie this into a neat little bow and as nod to Brad’s article, do we need a global documentation platform?

---

Big thanks to Jeremy Keith for encouraging me to write this after I ranted at him about it for half an hour on a call.