6 ms·

I hope they keep an eye on contribution statistics post this change. I've said it before, but I think this move was a mistake. They've thrown away the benefit

by lol768 6y ago

I hope they keep an eye on contribution statistics post this change. 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. When I last brought this up, I was told that there were a number of contributors put off by the wiki-based nature of the previous iteration and they will now be excited to be able to contribute using Git. I'd honestly be interested to hear from any of these people. Given you could seamlessly login with your GitHub account, easily author your documentation and one-click preview your changes, 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?

lol768 6y ago
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.mozilla.org/en-US/docs/Web/Security/Certificate_Transparency https://web.archive.org/web/20200113175409/https://developer... To: https://github.com/mdn/content/blob/main/files/en-us/web/security/certificate_transparency/index.html 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.
- roblabla 6y ago
  https://github.com/mdn/content/blame/53ba7ccaf34f639208791a98171d80badfe0ff33/files/en-us/web/security/certificate_transparency/index.html https://github.com/mdn/content/blame/53ba7ccaf34f639208791a9... Isn't your entire article here? The history is there...
  - lol768 6y ago
    All of the contributor names, edit descriptions etc have been lost. It's not history, it's just snapshots of content.
    - bawolff 6y ago
      What license is MDN under and who owns the copyright? Is this a license violation?
      - escattone 6y ago
        https://github.com/mdn/content/blob/main/LICENSE.md 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/_wikihistory.json https://github.com/mdn/content/blob/main/files/en-us/_wikihi...
    - peterbe 6y ago
      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/Certificate_Transparency/contributors.txt 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.
  - merb 6y ago
    well... I'm still not sure why the old content was scratched. I mean https://developer.mozilla.org/en-US/docs/Web/Security/Certificate_Transparency https://developer.mozilla.org/en-US/docs/Web/Security/Certif... wtf?! this looks like a placeholder.
- oefrha 6y ago
  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.
  - lol768 6y ago
    > 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.
joshxyz 6y ago
> 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.
Vinnl 6y ago
> 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.
sradman 6y ago
> 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.
- breck 6y ago
  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.
- deleted 6y ago
  [deleted]
lutoma 6y ago
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.
- breck 6y ago
  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.
  - peterbe 6y ago
    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.
pradn 6y ago
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.
- peterbe 6y ago
  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.
  - gitweb 6y ago
    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.
  - pradn 6y ago
    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.
thiht 6y ago
> 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.
searchableguy 6y ago
> 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.
- peterbe 6y ago
  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 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 https://github.com/mdn/content/pull/152
- peterbe 6y ago
  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.
tottenhm 6y ago
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.
deleted 6y ago
[deleted]

by lol768 6y ago

lol768 6y ago

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.mozilla.org/en-US/docs/Web/Security/Certificate_Transparency https://web.archive.org/web/20200113175409/https://developer... To: https://github.com/mdn/content/blob/main/files/en-us/web/security/certificate_transparency/index.html 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.

roblabla 6y ago
https://github.com/mdn/content/blame/53ba7ccaf34f639208791a98171d80badfe0ff33/files/en-us/web/security/certificate_transparency/index.html https://github.com/mdn/content/blame/53ba7ccaf34f639208791a9... Isn't your entire article here? The history is there...
- lol768 6y ago
  All of the contributor names, edit descriptions etc have been lost. It's not history, it's just snapshots of content.
  - bawolff 6y ago
    What license is MDN under and who owns the copyright? Is this a license violation?
    - escattone 6y ago
      https://github.com/mdn/content/blob/main/LICENSE.md 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/_wikihistory.json https://github.com/mdn/content/blob/main/files/en-us/_wikihi...
  - peterbe 6y ago
    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/Certificate_Transparency/contributors.txt 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.
- merb 6y ago
  well... I'm still not sure why the old content was scratched. I mean https://developer.mozilla.org/en-US/docs/Web/Security/Certificate_Transparency https://developer.mozilla.org/en-US/docs/Web/Security/Certif... wtf?! this looks like a placeholder.
oefrha 6y ago
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.
- lol768 6y ago
  > 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.

joshxyz 6y ago

> 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.

Vinnl 6y ago

> 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.

sradman 6y ago

> 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.

breck 6y ago
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.
deleted 6y ago
[deleted]

lutoma 6y ago

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.

breck 6y ago
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.
- peterbe 6y ago
  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.

pradn 6y ago

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.

peterbe 6y ago
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.
- gitweb 6y ago
  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.
- pradn 6y ago
  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.

thiht 6y ago

> 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.

searchableguy 6y ago

> 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.

peterbe 6y ago
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 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 https://github.com/mdn/content/pull/152
peterbe 6y ago
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.

tottenhm 6y ago

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.

deleted 6y ago

[deleted]