Hacker News Reader

Addendum: wtf, this change (or a change that happened prior to the final dump from Kuma) appears to have lost almost the entirety of one of the articles I have contributed.

Compare: https://web.archive.org/web/20200113175409/https://developer...

To: https://github.com/mdn/content/blob/main/files/en-us/web/sec...

Where has all the content gone? And of course there's no history anymore due to how the content has been migrated.

https://github.com/mdn/content/blame/53ba7ccaf34f639208791a9...

Isn't your entire article here? The history is there...

All of the contributor names, edit descriptions etc have been lost. It's not history, it's just snapshots of content.

What license is MDN under and who owns the copyright? Is this a license violation?

https://github.com/mdn/content/blob/main/LICENSE.md and the attributions for the English docs are in https://github.com/mdn/content/blob/main/files/en-us/_wikihi...

The database dump is coming. Busy week.

Also, at the footer of every document is a link to `$0/contributors.txt`. Your attribution is there: https://developer.mozilla.org/en-US/docs/Web/Security/Certif...

There will be a record of every contributor who submitted a revision to the non-archived content in all locales.

well... I'm still not sure why the old content was scratched. I mean https://developer.mozilla.org/en-US/docs/Web/Security/Certif... wtf?! this looks like a placeholder.

Losing the entire history by starting with a dump is ridiculous. Authorship would be somewhat tricky (I suppose they could use username + email on file, but might run into issues where people don’t intend to make their email addresses public), but it’s not like it would be very hard to migrate the diff + message history to git. I guess they either don’t want to start the repo with a gazillion commits (actually that would be a good stress test for the system, but would make cloning harder for people who don’t know how to use --depth), or just don’t care?

Btw: now you need to clone the entire repository and run a dev server just to edit and preview a single page (let’s not get into super involved ways to clone only part of a git repo). You can avoid cloning by editing with GitHub’s web editor, but you can’t preview that way.

> I guess they either don’t want to start the repo with a gazillion commits

They could've cut it down to e.g. the last n changes to a page if this was a concern.

Honestly the whole migration feels like it has happened before things had been properly thought through. There are pages lying around with {{IncludeSubnav{"")}} directives in the text that don't render properly - and they put this into production.

I can't speak to MDN's tooling or culture, but... it sounds like the transition that many FOSS projects made from wiki-workflow docs (Confluence/Mediawiki/etc) to PR-workflow docs (ReadTheDocs/Github/mkdocs/etc).

Anecdotally, for the project where I contribute most... the issue about fewer contributors is real. But you do still get contributors, and PR-workflow makes other aspects easier (like broad clean-ups/reorgs/scheduling/versioning). For contributors who come, you also get the opportunity to socialize/engage them during review. Overall, there are drawbacks/risks, but I'd say it was a net-improvement (wrt quality/clarity of the final docs).

Maybe look at it this way: Both workflows provide a way to organize open/community docs. Both workflows have positive role-models. In both, you need capacity+interest for editing, for socialization, etc. If you tend to these, you can do good. But if there's neglect... then that's where you'll see the starkest differences:

* In wiki-workflow, the likely symptoms of neglect are draft-quality content, bad prose, quirky TOC, drive-by edits that are out-of-place, etc.

* In PR-workflow, the likely symptoms of neglect are slow review/feedback, older content, would-be contributors who can't assimilate to the workflow, etc.

> what exactly are you gaining from having the editor gone and now requiring a local docs environment to do all of the preview/edit/commit steps manually

Lets be real: internet points in my github profile contribution heatmap

Kidding aside tho, as a first-time contributor back then the non-markdown editor was clunky for me, the spaces the highlights were just un-natty. You're right about the non-instantaneous fix visibility tho, but for extra QA maybe it's a fair trade-off.

> I think this move was a mistake. They've thrown away the benefits of a incredible wiki-based platform

Ideally, you want to cater to both the CLI centric workflows of developers/build-systems and the WebUI centric workflows of everyone else (the old system). The Mozilla blog posts mention the JAMStack so I'm guessing that the intent was to port the server-side Django apps/editors to a browser-side framework like React or one of its alternatives.

If the design and implementation of the new platform was perfectly executed then only the new functionality would be apparent; both systems are essentially "wiki-based". Platform transitions are rarely seamless as your lost content/metadata clearly shows.

Yes, maybe someone from Mozilla could explain why they didn't port history and the current web app editing?

We are currently doing the same thing at Our World in Data and discussing this exactly so would be great to learn more about the design decisions.

> I've said it before, but I think this move was a mistake. They've thrown away the benefits of a incredible wiki-based platform (where changes were pretty much instantaneous and any of us could easily make a difference to the docs!), the (actually pretty decent) WYSIWYG editor and an overall frictionless editing experience and replaced it with what, some (not even Markdown) document files in a GitHub repository. I honestly believe this will dissuade people from making small, quick fixes and ultimately drive away contributors.

Yeah, I really agree with this. Having built a website which relied on people submitting PRs to add their content on GitHub - I wouldn't do it again. It's a lot of friction for both the maintainers and people contributing.

Every story has at least two sides. Check out some of the amazing PRs people have been able to do recently on https://github.com/mdn/content/pulls Being able to do scripts or grep + sed or other advances bulk edits is really cool. E.g. https://github.com/mdn/content/pull/152

Also, keep in mind all the tooling GitHub offers. Comments with reactions, quoting, permalinks, blocking, etc. Yes, it can be built in-house but would cost a fortune.

GitHub has incredibly high friction to get started. I don't see the antipathy toward WYSIWYG editors. It's one of the best human interface inventions we've come up with. Having to do a level of indirection about Markdown syntax is a pain, on top of remembering git commands.

What's cool about git as a persistent storage, is that you can use vscode, emacs, vim, or notepad. Or you can write a little web app that starts a WYSIWYG editor on localhost:8888 or Heroku and have it dump to the file system and then you just need to write a script that takes care of submitting the PR from there.

This, plus there are many server-side WYSIWYG markdown editors that make it transparent to the end user that they are even using Markdown. This is really the future IMO, you get the best of both worlds. Hopefully they'll add some extensions though to Markdown. I hope the community will create even more as well.

What I'm getting at is that we're misconstruing a storage system (git), with a user-friendly interface. Ideally we get the ubiquity and interoperability of git with a WYSIWYG editor. A website that lets you edit files in the browser and is backed by a git repo could be helpful. But maybe in edge cases, it'd still be too complex. Using git here seems like overkill.

> where changes were pretty much instantaneous

I don't know if I hit an exception, but I added a small change (a single clarifying example) to the RegEx page, which was listed on the dev environment's history for ages before actually becoming active.

Also keep in mind that, given MDN's target audience, especially the target contributors, GitHub is less of a barrier than it would be for other platforms.

But yes, of course it'd still be good to keep an eye on the contribution statistics to validate those assumptions.

I agree. I've personally noticed time and time again how git-based workflows discourage me personally from making small one-time changes like typo fixes compared to a wiki or similar. It's just so much more overhead to have to start up a CLI, edit the document, push a commit, open a pull request etc…

This is not to say there aren't advantages to the git-based workflow and it might be a valid choice for a technical audience like this, but to claim it as "huge advantage in terms of contribution workflow" seems questionable.

1. You can have both. Parts of our site (Our World in Data) the researchers edit via a GUI, but under the hood it is making a commit and pushing to GitHub. My guess is MDN just hasn't gotten around to that yet?

2. GitHub and GitLab are a lot better nowadays at allowing you to edit markdown docs via the web and preview the results in a few clicks. Not quite as frictionless as 1 click, however if you are an editor and are constantly bombarded by spam, probably saves a lot of time as you know the person who is making the change and they are forced to add an explanation via commit message.

1. That's right! But it's not really on the roadmaps either. One can hope that someone in the community writes a fancy web app wrapper for GitHub's API or something.

2. Yeah, it's really really convenient to submit a quick PR entirely in the GitHub Web UI. But I admit, we have some work to do make the previewing experience a bit better.

> They've thrown away the benefits of a incredible wiki-based platform (where changes were pretty much instantaneous and any of us could easily make a difference to the docs!), the (actually pretty decent) WYSIWYG editor and an overall frictionless editing experience and replaced it with what, some (not even Markdown) document files in a GitHub repository. I honestly believe this will dissuade people from making small, quick fixes and ultimately drive away contributors.

I'm only a sample of 1, but I once tried to edit a page and just couldn't find out how to do it. So I'm not sure their change will be any worse.