Join GitHub today
GitHub is home to over 36 million developers working together to host and review code, manage projects, and build software together.Sign up
Making use of Webmentions and structured data for adding framework-related info to MDN #1
From today's discussion, it was raised that it would be useful to add useful asides and helpful documentation on concerns to certain MDN pages that concern certain frameworks. It was mentioned that the format of this could be structured data, such as a separate JSON file.
Later during the discussion it was mentioned that maybe the frameworks docs should be linking to MDN pages and stating these concerns themselves, also providing useful traffic to MDN, and value (and motivation) for both sides.
There is an interesting technology, that is actually a web standard and could make this process more straightforward, while having all of the above properties: this could be achieved using Webmentions and structured data embedded in external websites/docs themselves.
When such a documentation piece is submitted to a framework's documentation, and a Webmention is received, MDN's infrastructure would do the parsing of the information and after a moderation step this note could be added to the appropriate MDN page (either manually, first, or by keeping the content of this Webmention in a JSON file and embedding the JSON file content using a macro).
This would encourage framework authors to keep this information up-to-date (e.g. if a framework is updated that resolves this caveat, the time they are updating the docs they notice the caveat is mentioned on MDN and can act/notify accordingly), drives content to MDN via the links, while the caveats/notes appearing after moderation on the appropriate MDN pages could drive high-value visits to the frameworks' docs site.
I'm going to cc @tantek who is a big advocate of the technology and I would imagine he would be happy to see it used in MDN, and also to sanity-check whether he agrees this is a good usecase for the tech.
https://github.com/flaki your understanding is correct. microformats2 (specifically microformats.org/wiki/h-entry for a https://indieweb.org/reply ) would work well to mark-up such useful asides and other notes / comments regarding MDN pages, notifying those pages using Webmention, and handling them accordingly via moderation etc.
How those asides or notes are displayed on the MDN page is up to the design of the MDN page.
In addition Webmention also allows for easily submitting updates to such asides, notes, and comments and having them handled automatically for accepted submissions, or again via a moderation step.
(Originally published at: https://tantek.com/2019/150/t2/)
referenced this issue
May 30, 2019
@flaki this is such a wonderful idea. I could see so many use cases. For one I know I would add a channel to my feed reader to watch for resource updates. I would know nothing about the web if it wasn't for MDN so knowing when a CSS Grid resource changes or drops would be great.
We would then be able to enable webmentions and I could see this being a huge community resource. Not just for the use cases you mention but also for people asking for help. Volunteer contributors could, for example, watch the reply feeds to resources and offer help. This lowers our reliance on toxic platforms like Twitter and facebook.
Plus would give cool user data when you have to create KPIs or whatever the acronym for goals are these days..
In fact, long term pie in the sky new communities apps could be created. For example there are new micropub clients everyday. Down the road a PWA could be invented called "Help MDN, Your My Only Hope" and its basically publishes a reply post to a resource someone is reading.
Most importantly it models good practice about using HTML. All of these benefits, from the immediate to the vaporware, are made possible by keeping your metadata in a human readable text.
I would happy to help in any way I can (though I would start by updating this page: https://developer.mozilla.org/en-US/docs/Web/HTML/microformats to match microformats.org/wiki/)