9 ms·

Welcome Yari: MDN Web Docs has a new platform

262 points by Garbage 6y ago

tasogare 6y ago
Awful logo. The designer could have made the I a lance instead of that full blown weeby character.
- peanut_worm 6y ago
  I have to agree. I think a Yari is the type of spear he has but it looks like a badly vectorized screenshot from Tekken.
- adamsea 6y ago
  Agreed. Plus why name the thing / use the icon of a lance, anyway? So confusing.
  - ngokevin 6y ago
    Project names with a random word taken from another language always felt a bit cheesy to me.
- zabhi 6y ago
  Yari in Hindi reads as friendship. I have been going by that so far, and refuse to accept any other meaning.
- Hedja 6y ago
  It's just a vectorised image of Yukimura from Samurai Warriors[1]. This image to be specific[2]. Don't think there was a designer, just a developer making a logo using a character they like (or maybe it was random image search). Pretty common in open source. [1] https://koei.fandom.com/wiki/Yukimura_Sanada https://koei.fandom.com/wiki/Yukimura_Sanada [2] https://static.wikia.nocookie.net/dynastywarriors/images/9/97/Yukimura-sw4.png https://static.wikia.nocookie.net/dynastywarriors/images/9/9...
  - Pfhreak 6y ago
    Isn't that just straight up copyright infringement? I understand that it's common in developer tooling to pick a character and use them as a logo, but it seems like a bold move to do that with some sort of external tooling at Mozilla's scale.
- cratermoon 6y ago
  Yari is a Japanese lance. http://www.ninpo.org/militaryhistory/weapons/yari.html http://www.ninpo.org/militaryhistory/weapons/yari.html If your complaint is about it being weeb, you need to start with complaining about the name itself.
SPBS 6y ago
Before I read this post I've never considered the fact that using git over an SQL database makes it easier for collaborating on documents, interesting!
- swiley 6y ago
  Most document editing software (including wikis) has a pretty mediocre collaboration UX. PRs/MRs are a genius idea and I wish git was used more often for collaboration on documentation.
  - est31 6y ago
    git has a high barrier of entry. I'm not sure you can get non technical people to use it. Although I agree that once you know git, collaboration is great.
    - jlokier 6y ago
      I agree. I know some people, who are good at writing, who were going to opt out of another documentation project if Git was used as the means of collaboration because they felt it was an unnecessary barrier to entry when a wiki is so much more straightforward. In the end we did use Git for documentation (pressure from devs), and in practice the non-devs tried to stay involved but ended up letting "technical" people do all the Git and diffing stuff, so it remained a practical barrier to involvement in the documents. People who are used to Git and development in general tend to forget that a lot of tools we take for granted, including text editors, terminals and command lines, are completely alien to non-developers and not everyone wants to learn that stuff for just one project. I've known developers struggle with Git too (when they don't use it often, or it's only used for 1 out of 10 of their projects), so I agree it can be a fairly high barrier.
      - leppr 6y ago
        I'm assuming the intended use-case will be clicking on a shortcut to Github's integrated "Edit & do pull-request" function embedded in the MDN website pages, and write one's edit in the Github editor GUI, which isn't bad. Anything closer to having to make a manual Github pull-request would be incredibly unergonomic for someone without an existing CLI setup for Github (ie. most developers).
byecomputer 6y ago
Anyone else find the link underline CSS to be distracting? My brain sees it as a strikethrough due to it being high up like that, sort of messes with the reading flow.
- theandrewbailey 6y ago
  No. You might want to check your browser defaults. There isn't any custom styling to those underlines.
  - byecomputer 6y ago
    Huh, on my desktop there isn't—thanks for pointing that out. My tablet uses Opera; I guess it doesn't support something about those links, but I'm not sure what.
- floatingatoll 6y ago
  It’s the same height as the ‘reply’ HN link, as far as I can see.
caddywompus 6y ago
Really glad to see this project continuing on. I do have concerns about being limited to Markdown syntax though. While Markdown has its place on small to medium sized projects, its simplicity quickly becomes a hindrance, and you end up falling back to html in Markdown. I could see something like ReStructuredText or Asciidoc being a better fit, if not a full blown enterprise style Docbooks or DITA system. Not a big fan of the logo, it is cool, but doesn't really inspire my inner web documentation. (edit) Actually no, I think its the size and style of the logo. Singling out the top of the spear and using that would be cool, but it reminds me too much of a fighting game character as is.
- caiob 6y ago
  The goal is to get more people involved. Doesn't it make sense to lower the entry barrier by implementing a more popular syntax?
  - caddywompus 6y ago
    Yes, that's definitely the balance to maintain. Ease of entry, vs tooling to manage the project as it grows. The main reason I see it being an inhibition is due to the size of the HTML spec, and the number of pages that it will need. I think this is why a lot of sites take markdown, then add their own extensions, like how there is "Github Markdown" among many other flavors. That's definitely one route, but I see something like ReStructuredText or Asciidoc as more mature and interoperable, while still being relatively easy to master in the same way as Markdown. Since they can both produce docbook output, vastly easing any migrations in the future by adhering to an industry standard.
  - peterbe 6y ago
    It's not that easy. We have 60+k pages carried over from 15 years of organic evolution. It's unstructured and messy. A move away from HTML to something "more popular syntax" (like Markdown) is NOT easy.
- gostsamo 6y ago
  They are not settled on markdown, so there is time for changing their mind.
ArtWomb 6y ago
I'm on MDN every day, and find it an essential resource! There's been an explosion of new Web APIs: atomics, devices, filesystems, crypto, payments, xr, and even proposals for neural nets in browser. Plenty of opportunity to become a domain expert and contribute live code ;)
T3RMINATED 6y ago
Yari has 19 0day exploits on the dweb. Bye Mozilla
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...
    - 6y ago
deleted 6y ago
[deleted]
senko 6y ago
An immediate benefit of using git over the old wiki platform - or any wiki platform, for that matter, is this: no matter what happens with whoever's in charge of maintaining Yari, the wide community still has full capability to continue using, improving, including the ability to see past changes.
ognarb 6y ago
Interesting that they are moving to a git based approach. In KDE, we did something very similar 3-4 months ago with moving most of our development tutorials from various sources (wikis, old pdf book, ...) to a new Hugo based documentation platform at https://develop.kde.org/docs https://develop.kde.org/docs The problem was that our documentation was bit rotting in the wiki and the previous mediaWiki wasn't working so well for having consistent formatting across pages, reviewing changes and organizing the content. Using the new Hugo based software, we now have a few very helpful macros to add links to Doxygen based documentation, include snippets of code from the library repository and automatic generation of navbars and the navigation. And we also get with Gitlab web editor an easy way for people to contribute. It is still like before one click away to edit the content. I probably should blog about it one day, but if someone want to check it out: https://invent.kde.org/documentation/develop-kde-org https://invent.kde.org/documentation/develop-kde-org.
- programbreeding 6y ago
  Just curious: What is the benefit/reason for the readfile shortcode for displaying code snippets as opposed to just pasting the code in and using the typical syntax highlighting? I suppose if the actual source file changes then the page would be updated as well which is neat, but if you're specifying certain lines to read from then that could easily become a problem. Considering how few shortcodes you're using I just felt like there must be a good reason to use it in this way and I was curious why.
  - ognarb 6y ago
    The readfile shortcode was added because this sort of code inclusion was used previously and when converting the documentation I needed something with similar semantic. Another advantage is that it allows me to have a compilable code examples that can be easily downloaded using gitlab support for creating zip from directories[0]. More interesting are the doxysnippet shortcode[1] that provides the extraction from the source code or the custom rendering of links[2] that allows this sort of markdown links: [Overlay](docs:kirigami2;OverlayDrawer) [0]: https://invent.kde.org/documentation/develop-kde-org/-/archive/developement/develop-kde-org-developement.zip?path=content/docs/getting-started/commandline https://invent.kde.org/documentation/develop-kde-org/-/archi... [1]: https://invent.kde.org/documentation/develop-kde-org/-/blob/developement/layouts/shortcodes/doxysnippet.html https://invent.kde.org/documentation/develop-kde-org/-/blob/... [2]: https://invent.kde.org/documentation/develop-kde-org/-/blob/developement/layouts/docs/_markup/render-link.html https://invent.kde.org/documentation/develop-kde-org/-/blob/...
techsin101 6y ago
the problem with crowd sourced docs is that nobody is interested in writing out very technical details especially for new apis, they are just left forever in dust. Popular stuff gets covered to death. But good lucking finding exact params for Web RTC sdp offer.
- peterbe 6y ago
  MDN is powered by a mix of people paid (by Mozilla, Google, Samsung, Microsoft) and contributors who volunteer their time.
martimarkov 6y ago
Just wondering: why keep MySQL and not move to PostgreSQL? I have been migrating all my projects to PostgreSQL because of personal believes (most of the time) and haven’t had any issues so I’m just wondering on the thought process.
- martimarkov 6y ago
  Love the downvote for asking a question :/
  - lexicality 6y ago
    You're being downvoted because your question has nothing to do with the article. Try StackOverflow instead?
    - martimarkov 6y ago
      Umm... it’s about Mozilla’s rebuild of their system. I think it’s a valid question based on the fact that they have changed the architecture, languages and rendering but kept the SQL server the same. So no, my question is it’s 100% relevant. I’m guess the downvotes is the community just getting a bit toxic on DBs.
      - lexicality 6y ago
        They didn't keep the SQL server, they got rid of it and migrated to having everything stored in static files in Git.
    - kzrdude 6y ago
      Lol on stackoverflow one is not just downvoted, but forced to say sorry for asking the question when it's not deemed good enough
- peterbe 6y ago
  PostgresSQL is better. We're all aware of that. But it's miniscule in importance. Especially if you use the ORMs and other decent tooling. The move to git isn't MySQL's fault. It's so more and bigger than that.
mileycyrusXOXO 6y ago
MDN is one of the most important websites in my day to day life a change like this makes me nervous. Hopefully it is for the better - but I'm worried it might be for the worse.
- peterbe 6y ago
  Why would it be for the worse?
happy_pancake 6y ago
Loads fast and looks great. Works for me!
- peterbe 6y ago
  This is just the beginning. Finally we can do the kind of web performance improvements we couldn't do on the old platform. But to boot, we gained 10-20% on the First Render metrics. And because of the whole new way we deploy, we went from a 27% hit ratio (of popular pages) to 96% in the CDN. That means ~70% of the time you gain about 300-500ms on the initial load. And besides, before, cold cache misses in the CDN would result in a backend server rendering whereas now a cold cache miss just means an S3 lookup.
freeopinion 6y ago
So MDN is now controlled by... Microsoft? And Microsoft's browser is now controlled by... Google? Maybe this bold new world is better. Maybe I'm just old and brittle. Or maybe we really have lost something that was good.
- hxjdbzkvksnaj 6y ago
  > So MDN is now controlled by... Microsoft? No. MDN is using a Microsoft platform as a front-end to attract contributors to their git repo, as most open-source projects do. If a company uses Gmail, does Google control the company? Github is a contractor for ICE, does Microsoft control US immigration enforcement? I don’t like Microsoft owning Github but there is a broad, easily-seen line between reasonable objection and this absurd overstatement.
  - freeopinion 6y ago
    > If a company uses Gmail, does Google control the company? If the only way to interact with coworkers, customers, investors, etc. is through Gmail, then, well. yes. If you can't be an employee without a Google login, then, ummm, yes. If Google can suspend your account and lock you out of your workplace, then yes. If a Google outage means you can't work, then yes. If Google loses some email and it means you can't continue a product launch... If a Google breach means that your company has been compromised... On the otherhand, if Github is just one avenue for contribution, well ok. Is this mirrored on Gitlab or git.mozilla.org or somewhere else that people can contribute without a Microsoft account? If Github fails is MDN just a flip-of-a-switch or less away from routing around it? Edit: typo
- deleted 6y ago
  [deleted]
tannhaeuser 6y ago
I've always loved MDN and wish them well, but - how is it acceptable to run off github for a project that wants to encourage authoring sites on a supposedly federated medium (the web)? - do we really need an enormous "web documentation project" for something entirely man-made, and which once set out to facilitate easy self-publishing? Even thinking about these and similar questions means that, rather than attempting to document the craptastic overcomplicated web, we're probably better off to leave the web behind us for good, and start to concentrate on defining HTML+CSS subsets (such as for purely static docs, for light content apps, and so on), to distribute simple static text via alternate p2p protocols. W3C and WHATWG have failed miserably to do so.
- breck 6y ago
  > - how is it acceptable to run off github for a project that wants to encourage authoring sites on a supposedly federated medium (the web)? You may have a point here in reality, but "technically" it should be very easy to push to multiple backends (GitLab, for example). So I could see lock-in to GitHub not ever being more than a hypothetical problem.
- bastawhiz 6y ago
  > do we really need an enormous "web documentation project" for something entirely man-made, and which once set out to facilitate easy self-publishing? What point are you trying to make? Should Oracle throw out its docs for Java because it's a large language that's man-made and designed for easily writing software—but lots of folks here think it's not good? > start to concentrate on defining HTML+CSS subsets (such as for purely static docs, for light content apps, and so on), to distribute simple static text via alternate p2p protocols And this will still require docs, and tutorials, and information about the P2P protocol, and how it's kept secure and ~anonymous, and how to facilitate discovery, and how to avoid a network partition, and how to build non-static tools like search engines, and how to securely interact with those tools, and how to do archival work, and a million other things that make that system an ecosystem...it's not easy to build a resilient distributed network that actually works. The fact of the matter is that people use the web whether you think it's good or not, and having decent docs for it is important. Nothing is stopping you or anyone else from building an alternate web, but so far there hasn't been anything that people actually care to use.
yarri 6y ago
The name choice is so close...
- peterbe 6y ago
  Sorry(?) But it's still just MDN (or MDN Web Docs). Yari is just the code name for the code repo. Not a particularly important name.
  - breck 6y ago
    see op's username :)
whereistimbo 6y ago
Tried visiting https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_client_applications https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_... , noticed that the sidebar which contains links to related resources gone. Also since it's based on markdown, would hosting MDN locally be possible now?
- peterbe 6y ago
  Can you scroll to the bottom of that page and use the "Report a problem with this content on GitHub" link? The raw content is not Markdown. It's HTML with some macros (called kumascript macros). And yes, you can "host MDN locally" now. Before you had to write a web scraper, now you can just iterate over the files after a `git clone`. But you might need Yari to build the raw HTML to fully formed HTML that you can open in your browser.
pjmlp 6y ago
Some MDN links are broken (Camera docs) where do we report them?
- peterbe 6y ago
  On every document, there are appropriate links at the bottom .
  - pjmlp 6y ago
    Thanks, I reported it.

262 points by Garbage 6y ago

tasogare 6y ago

Awful logo. The designer could have made the I a lance instead of that full blown weeby character.

peanut_worm 6y ago
I have to agree. I think a Yari is the type of spear he has but it looks like a badly vectorized screenshot from Tekken.
adamsea 6y ago
Agreed. Plus why name the thing / use the icon of a lance, anyway? So confusing.
- ngokevin 6y ago
  Project names with a random word taken from another language always felt a bit cheesy to me.
zabhi 6y ago
Yari in Hindi reads as friendship. I have been going by that so far, and refuse to accept any other meaning.
Hedja 6y ago
It's just a vectorised image of Yukimura from Samurai Warriors[1]. This image to be specific[2]. Don't think there was a designer, just a developer making a logo using a character they like (or maybe it was random image search). Pretty common in open source. [1] https://koei.fandom.com/wiki/Yukimura_Sanada https://koei.fandom.com/wiki/Yukimura_Sanada [2] https://static.wikia.nocookie.net/dynastywarriors/images/9/97/Yukimura-sw4.png https://static.wikia.nocookie.net/dynastywarriors/images/9/9...
- Pfhreak 6y ago
  Isn't that just straight up copyright infringement? I understand that it's common in developer tooling to pick a character and use them as a logo, but it seems like a bold move to do that with some sort of external tooling at Mozilla's scale.
cratermoon 6y ago
Yari is a Japanese lance. http://www.ninpo.org/militaryhistory/weapons/yari.html http://www.ninpo.org/militaryhistory/weapons/yari.html If your complaint is about it being weeb, you need to start with complaining about the name itself.

SPBS 6y ago

Before I read this post I've never considered the fact that using git over an SQL database makes it easier for collaborating on documents, interesting!

swiley 6y ago
Most document editing software (including wikis) has a pretty mediocre collaboration UX. PRs/MRs are a genius idea and I wish git was used more often for collaboration on documentation.
- est31 6y ago
  git has a high barrier of entry. I'm not sure you can get non technical people to use it. Although I agree that once you know git, collaboration is great.
  - jlokier 6y ago
    I agree. I know some people, who are good at writing, who were going to opt out of another documentation project if Git was used as the means of collaboration because they felt it was an unnecessary barrier to entry when a wiki is so much more straightforward. In the end we did use Git for documentation (pressure from devs), and in practice the non-devs tried to stay involved but ended up letting "technical" people do all the Git and diffing stuff, so it remained a practical barrier to involvement in the documents. People who are used to Git and development in general tend to forget that a lot of tools we take for granted, including text editors, terminals and command lines, are completely alien to non-developers and not everyone wants to learn that stuff for just one project. I've known developers struggle with Git too (when they don't use it often, or it's only used for 1 out of 10 of their projects), so I agree it can be a fairly high barrier.
    - leppr 6y ago
      I'm assuming the intended use-case will be clicking on a shortcut to Github's integrated "Edit & do pull-request" function embedded in the MDN website pages, and write one's edit in the Github editor GUI, which isn't bad. Anything closer to having to make a manual Github pull-request would be incredibly unergonomic for someone without an existing CLI setup for Github (ie. most developers).

byecomputer 6y ago

Anyone else find the link underline CSS to be distracting? My brain sees it as a strikethrough due to it being high up like that, sort of messes with the reading flow.

theandrewbailey 6y ago
No. You might want to check your browser defaults. There isn't any custom styling to those underlines.
- byecomputer 6y ago
  Huh, on my desktop there isn't—thanks for pointing that out. My tablet uses Opera; I guess it doesn't support something about those links, but I'm not sure what.
floatingatoll 6y ago
It’s the same height as the ‘reply’ HN link, as far as I can see.

caddywompus 6y ago

Really glad to see this project continuing on. I do have concerns about being limited to Markdown syntax though. While Markdown has its place on small to medium sized projects, its simplicity quickly becomes a hindrance, and you end up falling back to html in Markdown. I could see something like ReStructuredText or Asciidoc being a better fit, if not a full blown enterprise style Docbooks or DITA system. Not a big fan of the logo, it is cool, but doesn't really inspire my inner web documentation. (edit) Actually no, I think its the size and style of the logo. Singling out the top of the spear and using that would be cool, but it reminds me too much of a fighting game character as is.

caiob 6y ago
The goal is to get more people involved. Doesn't it make sense to lower the entry barrier by implementing a more popular syntax?
- caddywompus 6y ago
  Yes, that's definitely the balance to maintain. Ease of entry, vs tooling to manage the project as it grows. The main reason I see it being an inhibition is due to the size of the HTML spec, and the number of pages that it will need. I think this is why a lot of sites take markdown, then add their own extensions, like how there is "Github Markdown" among many other flavors. That's definitely one route, but I see something like ReStructuredText or Asciidoc as more mature and interoperable, while still being relatively easy to master in the same way as Markdown. Since they can both produce docbook output, vastly easing any migrations in the future by adhering to an industry standard.
- peterbe 6y ago
  It's not that easy. We have 60+k pages carried over from 15 years of organic evolution. It's unstructured and messy. A move away from HTML to something "more popular syntax" (like Markdown) is NOT easy.
gostsamo 6y ago
They are not settled on markdown, so there is time for changing their mind.

ArtWomb 6y ago

I'm on MDN every day, and find it an essential resource! There's been an explosion of new Web APIs: atomics, devices, filesystems, crypto, payments, xr, and even proposals for neural nets in browser. Plenty of opportunity to become a domain expert and contribute live code ;)

T3RMINATED 6y ago

Yari has 19 0day exploits on the dweb. Bye Mozilla

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

deleted 6y ago

[deleted]

senko 6y ago

An immediate benefit of using git over the old wiki platform - or any wiki platform, for that matter, is this: no matter what happens with whoever's in charge of maintaining Yari, the wide community still has full capability to continue using, improving, including the ability to see past changes.

ognarb 6y ago

Interesting that they are moving to a git based approach. In KDE, we did something very similar 3-4 months ago with moving most of our development tutorials from various sources (wikis, old pdf book, ...) to a new Hugo based documentation platform at https://develop.kde.org/docs https://develop.kde.org/docs The problem was that our documentation was bit rotting in the wiki and the previous mediaWiki wasn't working so well for having consistent formatting across pages, reviewing changes and organizing the content. Using the new Hugo based software, we now have a few very helpful macros to add links to Doxygen based documentation, include snippets of code from the library repository and automatic generation of navbars and the navigation. And we also get with Gitlab web editor an easy way for people to contribute. It is still like before one click away to edit the content. I probably should blog about it one day, but if someone want to check it out: https://invent.kde.org/documentation/develop-kde-org https://invent.kde.org/documentation/develop-kde-org.

programbreeding 6y ago
Just curious: What is the benefit/reason for the readfile shortcode for displaying code snippets as opposed to just pasting the code in and using the typical syntax highlighting? I suppose if the actual source file changes then the page would be updated as well which is neat, but if you're specifying certain lines to read from then that could easily become a problem. Considering how few shortcodes you're using I just felt like there must be a good reason to use it in this way and I was curious why.
- ognarb 6y ago
  The readfile shortcode was added because this sort of code inclusion was used previously and when converting the documentation I needed something with similar semantic. Another advantage is that it allows me to have a compilable code examples that can be easily downloaded using gitlab support for creating zip from directories[0]. More interesting are the doxysnippet shortcode[1] that provides the extraction from the source code or the custom rendering of links[2] that allows this sort of markdown links: [Overlay](docs:kirigami2;OverlayDrawer) [0]: https://invent.kde.org/documentation/develop-kde-org/-/archive/developement/develop-kde-org-developement.zip?path=content/docs/getting-started/commandline https://invent.kde.org/documentation/develop-kde-org/-/archi... [1]: https://invent.kde.org/documentation/develop-kde-org/-/blob/developement/layouts/shortcodes/doxysnippet.html https://invent.kde.org/documentation/develop-kde-org/-/blob/... [2]: https://invent.kde.org/documentation/develop-kde-org/-/blob/developement/layouts/docs/_markup/render-link.html https://invent.kde.org/documentation/develop-kde-org/-/blob/...

techsin101 6y ago

the problem with crowd sourced docs is that nobody is interested in writing out very technical details especially for new apis, they are just left forever in dust. Popular stuff gets covered to death. But good lucking finding exact params for Web RTC sdp offer.

peterbe 6y ago
MDN is powered by a mix of people paid (by Mozilla, Google, Samsung, Microsoft) and contributors who volunteer their time.

martimarkov 6y ago

Just wondering: why keep MySQL and not move to PostgreSQL? I have been migrating all my projects to PostgreSQL because of personal believes (most of the time) and haven’t had any issues so I’m just wondering on the thought process.

martimarkov 6y ago
Love the downvote for asking a question :/
- lexicality 6y ago
  You're being downvoted because your question has nothing to do with the article. Try StackOverflow instead?
  - martimarkov 6y ago
    Umm... it’s about Mozilla’s rebuild of their system. I think it’s a valid question based on the fact that they have changed the architecture, languages and rendering but kept the SQL server the same. So no, my question is it’s 100% relevant. I’m guess the downvotes is the community just getting a bit toxic on DBs.
    - lexicality 6y ago
      They didn't keep the SQL server, they got rid of it and migrated to having everything stored in static files in Git.
  - kzrdude 6y ago
    Lol on stackoverflow one is not just downvoted, but forced to say sorry for asking the question when it's not deemed good enough
peterbe 6y ago
PostgresSQL is better. We're all aware of that. But it's miniscule in importance. Especially if you use the ORMs and other decent tooling. The move to git isn't MySQL's fault. It's so more and bigger than that.

mileycyrusXOXO 6y ago

MDN is one of the most important websites in my day to day life a change like this makes me nervous. Hopefully it is for the better - but I'm worried it might be for the worse.

peterbe 6y ago
Why would it be for the worse?

happy_pancake 6y ago

Loads fast and looks great. Works for me!

peterbe 6y ago
This is just the beginning. Finally we can do the kind of web performance improvements we couldn't do on the old platform. But to boot, we gained 10-20% on the First Render metrics. And because of the whole new way we deploy, we went from a 27% hit ratio (of popular pages) to 96% in the CDN. That means ~70% of the time you gain about 300-500ms on the initial load. And besides, before, cold cache misses in the CDN would result in a backend server rendering whereas now a cold cache miss just means an S3 lookup.

freeopinion 6y ago

So MDN is now controlled by... Microsoft? And Microsoft's browser is now controlled by... Google? Maybe this bold new world is better. Maybe I'm just old and brittle. Or maybe we really have lost something that was good.

hxjdbzkvksnaj 6y ago
> So MDN is now controlled by... Microsoft? No. MDN is using a Microsoft platform as a front-end to attract contributors to their git repo, as most open-source projects do. If a company uses Gmail, does Google control the company? Github is a contractor for ICE, does Microsoft control US immigration enforcement? I don’t like Microsoft owning Github but there is a broad, easily-seen line between reasonable objection and this absurd overstatement.
- freeopinion 6y ago
  > If a company uses Gmail, does Google control the company? If the only way to interact with coworkers, customers, investors, etc. is through Gmail, then, well. yes. If you can't be an employee without a Google login, then, ummm, yes. If Google can suspend your account and lock you out of your workplace, then yes. If a Google outage means you can't work, then yes. If Google loses some email and it means you can't continue a product launch... If a Google breach means that your company has been compromised... On the otherhand, if Github is just one avenue for contribution, well ok. Is this mirrored on Gitlab or git.mozilla.org or somewhere else that people can contribute without a Microsoft account? If Github fails is MDN just a flip-of-a-switch or less away from routing around it? Edit: typo
deleted 6y ago
[deleted]

tannhaeuser 6y ago

I've always loved MDN and wish them well, but - how is it acceptable to run off github for a project that wants to encourage authoring sites on a supposedly federated medium (the web)? - do we really need an enormous "web documentation project" for something entirely man-made, and which once set out to facilitate easy self-publishing? Even thinking about these and similar questions means that, rather than attempting to document the craptastic overcomplicated web, we're probably better off to leave the web behind us for good, and start to concentrate on defining HTML+CSS subsets (such as for purely static docs, for light content apps, and so on), to distribute simple static text via alternate p2p protocols. W3C and WHATWG have failed miserably to do so.

breck 6y ago
> - how is it acceptable to run off github for a project that wants to encourage authoring sites on a supposedly federated medium (the web)? You may have a point here in reality, but "technically" it should be very easy to push to multiple backends (GitLab, for example). So I could see lock-in to GitHub not ever being more than a hypothetical problem.
bastawhiz 6y ago
> do we really need an enormous "web documentation project" for something entirely man-made, and which once set out to facilitate easy self-publishing? What point are you trying to make? Should Oracle throw out its docs for Java because it's a large language that's man-made and designed for easily writing software—but lots of folks here think it's not good? > start to concentrate on defining HTML+CSS subsets (such as for purely static docs, for light content apps, and so on), to distribute simple static text via alternate p2p protocols And this will still require docs, and tutorials, and information about the P2P protocol, and how it's kept secure and ~anonymous, and how to facilitate discovery, and how to avoid a network partition, and how to build non-static tools like search engines, and how to securely interact with those tools, and how to do archival work, and a million other things that make that system an ecosystem...it's not easy to build a resilient distributed network that actually works. The fact of the matter is that people use the web whether you think it's good or not, and having decent docs for it is important. Nothing is stopping you or anyone else from building an alternate web, but so far there hasn't been anything that people actually care to use.

yarri 6y ago

The name choice is so close...

peterbe 6y ago
Sorry(?) But it's still just MDN (or MDN Web Docs). Yari is just the code name for the code repo. Not a particularly important name.
- breck 6y ago
  see op's username :)

whereistimbo 6y ago

Tried visiting https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_client_applications https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_... , noticed that the sidebar which contains links to related resources gone. Also since it's based on markdown, would hosting MDN locally be possible now?

peterbe 6y ago
Can you scroll to the bottom of that page and use the "Report a problem with this content on GitHub" link? The raw content is not Markdown. It's HTML with some macros (called kumascript macros). And yes, you can "host MDN locally" now. Before you had to write a web scraper, now you can just iterate over the files after a `git clone`. But you might need Yari to build the raw HTML to fully formed HTML that you can open in your browser.

pjmlp 6y ago

Some MDN links are broken (Camera docs) where do we report them?

peterbe 6y ago
On every document, there are appropriate links at the bottom .
- pjmlp 6y ago
  Thanks, I reported it.