MDN Web Docs evolves: Lowdown on the upcoming new platform
hacks.mozilla.org
hacks.mozilla.org
> "you will no longer be able to click Edit on a page, make and save a change, and have it show up nearly immediately on the page. You’ll also no longer be able to do your edits in a WYSIWYG editor."
> "you won’t have a WYSIWYG to instantly see what the page looks like as you add your content, and in addition you’ll be editing raw HTML"
They had a user-friendly system previously... Now users have to learn GitHub and author raw HTML! - I would point out that not all documentation writers are developers!
Ignoring the fact Microsoft's Github has recently had DMCA insanity, a proprietary frontend, and recently enforced Webcomponents (effectively removing UXP devs who were forced to self-host Gitea just to continue working)... this seems like Mozilla is trying to outsource as much as possible from their own hosting. They also shutdown Firefox Send.
Perhaps Mozilla is having issues / unable afford their own hosting anymore?
IIRC it was being abused and there was no way to combat that
If I think of serving user-generated/uploaded content, malware and copyright violations come directly to my mind.
Github's response: "... further degradation is a likelihood. I appreciate that this is disappointing and frustrating for you..." - https://forum.palemoon.org/viewtopic.php?p=202146#p202146
The other comment here about how it's like complaining it does not work in IE6 is really pertinent: Yes it damn well should, because I should not need the latest technology just to do something that would've been perfectly possible with the technology of TWO DECADES AGO. It should be entirely possible to use GitHub with a text-based browser because none of its interactions require anything more than that.
It's sad that I could probably write a more accessible interface in less time and resources, and I haven't even done much in the way of web development, yet dedicated web-developers with uninhibited trendchasing mentality will fuck it up so badly with this constant need for useless breaking changes.
Seriously, fuck this "modern" bullshit.
https://news.ycombinator.com/item?id=23136688
Would it be possible to make a form with all those features and that works (at least with 95% of the features) with your legacy (dead) browser of choice, be it IE6 or Pale Moon? Sure, it would. But to do that, GitHub would need to spend a lot of resources, even though most GitHub users do not need those dead browsers. Those browsers don’t support many modern APIs that web apps need, or that make developers’ lives easier.
Speaking of dead software, Pale Moon dropped support for Windows XP in 2016 [2]. What happened? Why does software drop support for old runtime environments? Because nobody has the time and resources to test things on XP, and to write polyfills for features that XP does not support, or to skip some features because they don’t want XP users to get a worse browser, and because new features can make your software better for the user or more secure.
The world has moved on. Install a modern version of Firefox (or Chrome/ium if you must) and stop complaining.
[1]: https://caniuse.com/?search=components
[2]: https://en.wikipedia.org/wiki/Pale_Moon_(web_browser)#Releas...
Not that I think this is the right move by Github, but you can create PRs from external tools. I do that from Magit+Forge all the time.
Sadly I think we are seeing Mozilla go the way of Netscape, and I would not be surprised if they sell off all the IP to someone soon
or just make FireFox yet another Chromium Skin
In late 2017, I spent upwards of 80+ hours standardizing 80 different MDN docs pages so they used the same best-practices layout as other more popular docs pages on the MDN.[1]
Of the 85 pages I updated to have better formatting, over 18 were reverted by random contributors within 2 days with no reason or explanation in the changelog. It was _impossible_ for me to get in contact with the people reverting the changes, because they are only a username.
I tried contacting MDN maintainers on IRC, searching for those users on IRC, and came up empty handed. I was left to make a plea on the mailing list asking for those change authors to get in contact with me, only to receive no response.
I came away from the experience highly encouraged not to contribute to the MDN.
So you'll need to know HTML and how to create a Pull Request on GitHub to be able contribute to documentation about web development... I feel like if you're writing about web development topics, that doesn't seem like a high bar to pass.
Let's stop acting like just because we can think of one downside that we can ignore the rest of the trade-offs. Btw this is a trade-off they already mentioned in TFA rehashed by an HN comment for some reason.
Did they confirm you have to write raw HTML? Markdown seems vastly more likely to me.
This is a strange thing to gripe about.
TFA goes into why this wasn't user friendly. You haven't responded to their own justifications. You've just reposted a trade-off that the TFA acknowledges and justifies.
Also rolling your own wiki is beyond stupid in this day and age. Just import all the MDN articles to MediaWiki. Making a script for this is a one-person weekend project. As I understand it though, Mozilla owns the copyright to all the content and they might shut you down for doing so.
MDN won't become better if there's more contributors and activity (churn).
It should be doable to create a WYSIWYG editor just for the MDN pages as well, or any static site generator for that matter. Question is whether they want to invest in that; will that actually improve things, given how the MDN pages are all fairly uniform in look, feel & layout.
I've thought of GitHub REST API Pull Requests [1] this requires authorizing web application though.
Another version - is there any service that allows to post changes in Pull Request body? Maybe extend GitLab? Workflow would be Edit page, Preview, copy to clipboard, open new Pull Request, paste.
I am not a fun of Markdown anymore. WYSIWYG looks like much better approach, it already there. HTML to markdown tools are not great.
[1] https://docs.github.com/en/free-pro-team@latest/rest/referen...
1. Netscape DevEdge
2. MediaWiki
3. Deki Wiki (renamed to MindTouch, closed source since 2013)
4. Kuma
5. Yari
There's a nice history here: https://developer.mozilla.org/en-US/docs/MDN_at_ten/History_...
When the platform changed and my attributions were lost, I stopped contributing. I had no street cred anymore. I was angry.
The switch to GitHub means the same problem once again. Nice way to alienate your community, MDN. Good luck with that.
Specially now that they fired every single paid worker.
Warm fuzzy feelings? The knowledge that people read your article thousands of times every day?
Honestly, while I agree that it’s a bit sad to lose the attribution, I find it hard to be sympathetic with people who get salty over losing internet points.
It’s a knowledge base. It’s well designed documentation. Something that many folks in IT lack at times. Showing people you can properly document knowledge in a collaborative way helps you get hired.
No idea if MDN are planning to do that though.
How can you be angry? MDN isn't yours. Do they owe you something? It's volunteer work. You're not owed anything. You should consider attribution a privilege.
Volunteer projects rely on an unspoken contract that symbolic recognition, awarded fairly, is a real motivation. And if a project wants to succeed, it needs to take that seriously.
Does the project owe its contributors anything? Legally, no. But if it wants to survive and keep contributors, then it had better damn well work hard to recognize them. The project isn't owed anything. The project should consider its free, voluntary member contributions a privilege.
Understand now?
Uh, what? Legally, yes.
Why are so many people (see sibling below: "Perhaps legally, in this case, they're owed nothing") just rolling with the suggestion that this is a grey moral issue and not a legal one? It's more than a moral issue. This is Creative Commons content. Mozilla doesn't acquire ownership of project contributors' work...
Once again, we have another Mozilla-related thread where we find two "sides" of an issue, with both offering takes that reveal that neither has any idea what they're talking about. What is it about Mozilla that attracts this sort of thing?
But I don't know why you're then choosing to baselessly insult people who discuss things about Mozilla...? Call me crazy, but I don't think that's a helpful or constructive attitude here...
It's neither baseless nor is it an attitude that is not "helpful"—I laid out exactly what the basis for the comment is, which comes almost directly from Frank Hecker's post a couple months ago after the most recent layoffs:
> Incidentally, doing a Twitter search on ”Mozilla” gives a good feel for public perception of Mozilla among technologists, but unfortunately most of the people commenting have no real idea what they’re talking about.
https://civilityandtruth.com/2020/08/13/mozillas-uncertain-f...
On the other hand posting false or simply misleading information, whether intentional or unintentional, is unhelpful. And if it's unintentional, there are a few different ways to respond when someone points it out. One way is to feel insulted and post an emotional response. Another is something like, "Oops, my mistake. I wasn't really thinking about that when I wrote what I did, but on second thought: good point!"
I don't really know what your first two sentences about human organizations and context are supposed to mean. Mozilla does have a legal obligation to abide by the license terms—in contrast to what you wrote—and that's pretty much that.
They're mean that you have completely misinterpreted the conversation, and apparently continue to do so.
The discussion started about moral responsibility. You're the only one confusing it with legal responsibility. And that's pretty much that.
You can't rewrite history. (And we shouldn't have to replay all this. It's still all there to see...)
The project doesn't owe the contributors anything legally in terms of recognition (or payment, etc.) which was the subject being discussed. That's quite obvious from the context.
Nobody ever brought up legal ownership of content at all -- that's 100% your misinterpretation.
It's kind of amazing how you misunderstand comments and then go on to insult others for supposedly misunderstanding comments... and then proceed to then do it all over a second time! Amusingly ironic. Better luck in the future, my friend... ;)
- "MDN isn't yours."
- "Do they owe you something?'
- "You're not owed anything."
... and your response? "Legally, no"—but of course the problem with that response, again, is that legally, yes; they do owe something.
So try rewriting the context and all the rhetorical gerrymandering you want, but it doesn't change that the fact that (a) there was a discussion in terms of legal responsibilities and (b) in that discussion about those responsibilities, your comments were incorrect. Being wrong because of a slip-up is fine—and it wasn't even wholly your slip-up; you were yes-anding someone else's comment. But this scrambling now to double down after it's pointed out and the subsequent projection—particularly in your last paragraph here—is more than a little annoying to encounter.
> The project doesn't owe the contributors anything legally in terms of recognition
... except they do, for the reasons already stated. Maybe there's some attempt at sleight of hand in your choice of the word "recognition" here (i.e., as distinct from "attribution", but even then, it's not clear whether any argument there, if there is one, would even hold up)—but it's not really important. Because "attribution" is the word that was used, attribution is what the BY part of CC-BY-SA stands for, and attribution is what's required by that license—yes, legally.
It's pretty bewildering that you think you have an argument here.
I mean, I dedicated an entire paragraph above that comment to pointing out moral possible legal problems, and used "perhaps" as an explicit indicator of uncertainty and doubt. The moral issue isn't particularly grey. The legal one...
There are various attributions for "Mozilla Contributors". Does that technically suffice under either the license terms or in juristictions which recognize authors rights? (What juristiction(s) apply - hosting provider, Mozilla's headquarters, or perhaps the original authors?) Do they perhaps more explicitly attribute the original authors elsewhere? Certainly stripping names from an explicit copyright header would almost certainly be a license violation, but does flattening VCS history in the manner also count as one? Did CC licensing terms apply at the time of previous CMS conversions? Were there perhaps contributor agreements and/or clickwrap licensing agreements previously which would've made this legal? Are there more buried attributions which might technically meet the burden of attribution while still being done poorly enough to feel slighted? Perhaps in some juristictions but not in others?
Can you answer all that with enough certainty as to assert that you "have any idea what you're talking about"?
> What is it about Mozilla that attracts this sort of thing?
Both sides offering takes that reveal that neither has any idea what they're talking about is far from unique to threads involving Mozilla. I dare say it's not even unique to the internet.
Also not grey—same as before.
> Can you answer all that with enough certainty as to assert that you "have any idea what you're talking about"?
Hey there. I'm a former Mozillian. I was a heavy contributor to Devmo in its early days (2006–2008). A bunch of that content is mine. It's not Mozilla's, and I know on what terms I made it available. So to answer your question quoted above (a) yes, in fact, I do know what I'm talking about, and (b) I don't have to be able to give an answer for every slot in your contrived matrix; it suffices if I'm able to say, "hey, you can't do that with the pieces that belong to me". And that's something that I can say—with certainty.
What’s happens in the real world is that you abide by contractual agreements and if a party breaks the agreement, you sue them for breach of contract. This also requires that you can sue them for breach of contract. Otherwise, you can kick dirt.
Understand now?
GP is venting some anger here at a relevant moment and the perspective is obviously valuable.
Perhaps legally, in this case, they're owed nothing - but it's not unreasonable to consider stripping said attributions to be a dick move, even when legal. Maybe unsuprising, but a dick move nonetheless.
Yeah, they do owe something: they owe the attribution which is a condition of the Creative Commons license which is what license the content is available to Mozilla (and everyone else) under.
> You should consider attribution a privilege.
Absolutely not. That's not how copyright works. What a deluded, entitled take.
But from the social contract, attribution is a perfectly fair expectation for this kind of work -- especially because at the time of, and even going forward, attribution was given. It may not have been codified as a public contract, but the relationship was, and is, quite clear.
And the breaking of that relationship for fairly arbitrary reasons (it couldn't be imported/converted?) is a pretty damn good reason to be annoyed -- hell, what other reason would you consider valid? If it was financial rather than social, you don't get angry, you get even (lawsuit).
Now I'm getting annoyed as I write this; its not a fucking privilege to have been given the honor of doing volunteer labor, and its not a fucking privilege to be given attribution for it -- it's like the most basic free compensation you can give for free work. It's a norm across the board
Mozilla is allegedly an open source project, so yes they owe you things based on free software principles, such as attribution and right to fork.
I mean Mozilla earns hundreds of millions a year and pays its CEO several millions a year, they could have well afforded to not violate your rights by spending a few dev days on writing a proper importer scripts.
This is a longstanding debate in wiki/collaboratively written content, but it it interesting to note that Wikipedia and the other WMF projects have been pretty successful with the anyone can edit, revert or fix after. The review first model is used on specific pages, where it is called pending changes protection, although this is not really like a PR in that there is no comment functionality, and the standard for acceptance is lower--I don't remember the exact wording but it is closer to "this is not vandalism/not obviously wrong" rather than "I personally endorse this" much less "this is the community consensus." These edits have no special endorsement once approved and can still be changed by other editors freely. One benefit of the PR model is finality, once an issue/PR is decided no one else is supposed to open another one with virtually the same change. Wikipedia sort of has that via article talk pages, but there is of course no centralized "maintainer" to adjudicate each and every controversy. Also, many editors just don't check or even understand them.
On the other hand, MDN is probably sufficiently narrow in scope that a team of subject matter experts can competently manage contributions in a timely manner. Of course, by "narrow" I do mean basically every technology currently in use on the web, so... guess we'll see how realistic that is!
The more quality control you need the more often you just let the contributor prove themselves first. Meaning, you don't automatically approve their submissions, but you don't completely prevent them from writing either, at least for as much as your community have the resources to review.
To be fair, maybe people should view MDN skeptically just like they do Wikipedia. But I think it's valuable for it to be a reliable source and review-first is a good way to maintain that.
Frankly, I always felt the wiki model pretty much a show-stopper to making any real edits with no good UI for commit review and a good UI for having a granular discussion about your changes. Instead the UX is to burn a lot of time getting a large change through a bunch of potential reversion cycles while trying to communicate through talk page(s). It's a hoop that selects for die hards.
Translations aren't even that expensive, especially relative to the cost of producing the docs in the first place. It hurts me to see MDN so starved of resources that they can't pay for even that small piece.
MDN has been key to so many people's technical education. High-quality web documentation is an essential resource for those looking to elevate themselves into a technical career these days.
Much of the world (20%, according to their own research) is set to lose access to this vital body of knowledge.
Like I said in another comment, approximately nobody translates technical documentation for fun.
https://en.wikipedia.org/wiki/Province_of_Soria
https://es.wikipedia.org/wiki/Provincia_de_Soria
Notice that the English page seems obviously translated by a non-native speaker, which has some implications not favorable to Mozilla's behavior here, specifically that ESL people will contribute documentation in English that native English-language speakers won't even provide for themselves.
I was thinking more like https://www.mediawiki.org/wiki/Download vs https://www.mediawiki.org/wiki/Download/es
Ideally, you would have a master document in which some parts are shared across all translations (like the layout, the actual terms in the spec, browser compatibility information, etc), while other parts were localizable (like the field descriptions). Then when content was added/changed, it would be clear which parts of the translations needed updating, and you could either flag them as such for volunteers, or use machine translation as a stop-gap, or both.
With the architecture they described, however, your options are either to make the translations completely independent or to make translations completely machine translated, neither of which is a good solution.
I mean I don't think it's actually that big of a deal as long as they stick to basic HTML markup (paragraphs, bold/italics, etc), but you're already running into problems when you add links.
Not having multi-language support as a first-class citizen is a step backwards IMO. Especially considering the world is still getting connected at an enormous rate.
Personally I had some very good experiences with some translators, and it could work even better if Mozilla manages to tune and train them properly. (Like making so that manual fixes improve the algorithm)
Your comment is the same as people who saw the launch of Wikipedia and wondered who could possibly write articles and find citations for fun.
Hell, who would write hundreds of thousands of wiki articles about The Elder Scrolls universe for fun? https://en.uesp.net/wiki/Main_Page
70k articles, not hundreds of thousands,[1] and of those 70k fewer than 1/3 are translated to any other language.
And speaking as someone who was a system and content admin for a MediaWiki-powered fiction wiki of about 15k articles... there are not many people relative to the amount of content who are actually interested in contributing anything, much less improving or maintaining what's already there. It's a very, very small core of contributors.
Toward your example, the 161 "active" users[2] (meaning any number of edits in the last 30 days) as of today on English UESP combined for 5,974 edits in that span. Of those edits, 4,779 were from 13 users. 3,039 — more than half of the last month's activity — were from the top 5 users.
On the non-English UESPs? No active users in Portuguese, one in Italian, none in Arabic.[3][4][5]
From my experience at least, it's because it's work — fun work, at times, but still work. Translating MDN content is also work. Doing _any_ documentation of _anything_ is work. Hell, I burned out on fiction documentation work before I burned out on paid work.
Some people do enjoy it! But voluntary documentation is still going to attract a small, specific core group of consistent contributors (if it attracts any at all).
[1] https://en.uesp.net/wiki/Special:Statistics
[2] https://en.uesp.net/w/index.php?title=Special:ActiveUsers&of...
[3] https://pt.uesp.net/wiki/Especial:Utilizadores_activos
[4] https://it.uesp.net/wiki/Speciale:UtentiAttivi
[5] https://ar.uesp.net/wiki/%D8%AE%D8%A7%D8%B5:%D9%85%D8%B3%D8%...
> Note: In addition, the text of the UI components and header menu will be in English only, going forward. They will not be translated, at least not initially.
But that's the easiest part! I understand the part about translations becoming stale, and how it's hard to manage, but honestly, translating a UI isn't that hard.
I think a good recipe to get better translations is:
- Don't treat it as an aftertought. Co-locate the en-US assets with the translated versions, that way your contributors actually see that there are other languages to support. Each page on the MDN website should be a folder containing a file for each language.
- If a translation is out-of-date, link to these more recent languages, and offer an auto-translated version in the meantime. Importantly, let the user switch between the automatic translation and the manual one. Also, make it obvious how they can contribute.
It's not like they were extremely profitable and fired people to squeeze an extra buck
Laying off people isn't inherently evil
Sure, one can rant all one wants about management's lack of business acumen, but that's completely separate from the issue of the layoffs
They had electron effectively a decade before electron with XULrunner and let it die on the vine.
There were opportunities for developer mindshare and for services adjacent to those tools they were already building... that they didn't do more for getting Thunderbird more competitive to Outlook to offering a better breed of messenger platform.
No, their management sat on fat cash, with fat paychecks and ill-conceived projects that lead to little in terms of mindshare or income longevity.
This is seriously entitled. Mozilla gave us an amazing resource, entirely for free. This attitude isn't right, it's toxic and harmful.
Mozilla is in a spot of difficulty, and instead of taking a resource that is operating entirely at a loss down, they're taking the engineering steps to ensure thez resource can outlive them.
That their mismanagement caused them the difficulty is entirely irrelevant here. It could have happened in a myriad of other ways. We should be praising Mozilla and the MDN tech team for the steps they're taking in making sure the MDN can live on.
Hint: it's less than $200.
Donations don't really work.
Just to be sure, are you referring to the "BuyMeCoffee" button on the GitHub page for the extension (https://github.com/VSCodeVim/Vim)?
That's what I expect of a non-profit organization dedicated to maintaining one of the last two remaining major browser engines, yes.
Now that antitrust is happening anyways, Google's main reason for shoveling money at them is going away.
I change, I publish, it's done. And if my change was wrong, or opinionated, or bad, it's just like that until somebody else catches it and fixes it back.
It seems to me that as far as the browser makers are concerned, MDN is as close to authoritative as you can get without going to the standards documents themselves - and the standards don't give you browser compatibility matrices or make any note of browser-specific quirks.
MDN may be a wiki, but it certainly isn't treated like one by the people who are most interested in it being accurate and up to date.
"Authoritative reference documents of MDN are going to become cluttered with comments and disagreements"
Which suggests previously authoritative docs are becoming less so due to being editable. I'm just pointing out they are and always have been subject to edits from the public. If anything the PR process will likely increase the reliability of the info because there would be a chance to do some vetting of changes.
I totally agree that MDN is as close to authoritative as you can get, but it's one (important) step away.
Every recent review I've seen of Wikipedia vs arbitrary big-a Authoritative sources has said that both have issues and overall Wikipedia is better.
But if what you said does happen, then RIP. It's not going to be the same - everyone is too busy writing medium articles to sell their course on udemy to make real contributions for free.
There were a lot of useful guides showing practical applications of features beyond just listing the api spec.
But I guess it'll still be useful as a more approachable wiki to api standards rather than having to go to w3schools (yuck) or the horrible ui of w3c.
PR model via GitHub, good.
That new platform schema diagram for Yari, looks complicated.
This is a similar tactic that MS has been using towards their documentation as well, so it's not so bad and for those most likely to contribute to technical documentation like this, the overlap with Github is significant enough.
What about the content part of it? Is it the hope that the move to GitHub and PR model will encourage broader community contribution and thus make up for the sad lack of dedicated content writers?
Jamstack is static sites/headless CMS, CDN for content/storage/speed, microservices/apis for data/auth/etc focused on speed, pre-rendering, and decoupling for easier swappable parts rather than monolith. [1]
It pushes the page rendering from runtime to build time.
It's Javascript, API, Markup. Put "pre-rendered" before "Markup" and you understand everything.
Maybe they do this because they really want to push the fact that you can serve the J and M from a CDN?
Real-time: dynamically generated on the server-side. (e.g. injecting the current user's username)
Occasionally: Jamstack (e.g. rebuilding a static site every time a contributors adds a blog post via the CMS)
Rarely: manual updates (e.g. manually deploying a new version of a small-town restaurant's website when the menu changes)
With a Wiki, even non-technical users can contribute, because the editing tools are all built in.
But with the PR model, now contributors need to understand HTML, CSS, Git, and GitHub PRs. I've been on GitHub for something like 10 years and I still have trouble figuring out PR workflows.
Making simple edits like grammar or punctuation fixes become significantly more effort in performing the submission than in performing the edit itself.
Wanting to have control over the submission process to prevent drive-by vandalism is certainly important. But that should be managed with role-based authentication and new users needing to have their edits approved by a moderator or by votes from long-term users in good standing. Once again, this sounds like the same old Mozilla line of "doing the right thing for the current user experience is too hard for our developers, so we're going to move the goalpost instead."
Compared to MSDN, MDN isn't as broad, but goes a lot deeper on topics, and has much better examples. Does Microsoft wring its hands over how much running MSDN costs, to the point of considering giving it up entirely? I don't think they do. I think they know that it's important to keep developers on-platform, in-ecosystem, and they do that by offering a comprehensive learning resource.
MDN is the best online resource for learning about Web technologies. I think a large part of that is because of the relatively low friction to edit. It not making Mozilla any money is completely their own fault. They could have taken that a step further and started offering training services and events. It stretches belief that you could have such a popular resource and can't figure out some sort of monetization strategy related to it. But, I guess, that's another of the same, old Mozilla lines.
Microsoft revenue stream is slightly more reliable than Mozilla's reliance on Google.
So... Ceding control over content to GitHub. Ceding control over uptime to Amazon. (Both done by a company that paints itself as pro-people, pro-privacy, etc.)
>You will no longer be able to click Edit on a page, make and save a change, and have it show up nearly immediately on the page. You’ll also no longer be able to do your edits in a WYSIWYG editor.
The fact that this is presented as some sort of improvement is pure farce.
The job of people who would have to check and approve the PRs becomes harder, too.
----
"You need permission
This form can only be viewed by users in the owner's organization."
Guys....
> Microsoft is joining Google, the W3C, and Samsung to make Mozilla’s MDN Web Docs as the single place for web API reference.
Now that Microsoft is on Chromium, and THAT is also documented in MDN, and Google and Microsoft both own public cloud providers.. I feel like this move is more a step in the evolution of MDN rather than Mozilla simply sending it out to pasture.
Will the quizzes disappear in the near future ? I was planning on brushing up my html/css/js skills and I was planning on doing it through MDN.
This would be a more solid argument if they were using a lot of AWS features together, but you could replace this with Minio and FastCGI if you really wanted to.
Shows two flowcharts, of which the new one is arguably more complex.