Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Making use of Webmentions and structured data for adding framework-related info to MDN #1

Open
flaki opened this issue May 30, 2019 · 3 comments

Comments

Projects
None yet
3 participants
@flaki
Copy link

commented May 30, 2019

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.

Microformats2 is a technology that allows embedding structured data into HTML websites themselves, exposing this structured information via a simple parser, extracting the information from the plain HTML. Framework authors could link to MDN with concerns, linking to the part of MDN concerned (e.g. JavaScript's setTimeout docs). MDN could provide docs how could framework authors provide structured information in a microformats2 format, right in their documentation itself and submit it to an MDN endpoint using WebMentions (alternatively, MDN could scrape popular docs pages for updates automatically).

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.

@flaki

This comment has been minimized.

Copy link
Author

commented May 30, 2019

cc @nomadtechie who brought up some of the points mentioned above during the discussion at the OpenJS Collab Summit session

@tantek

This comment has been minimized.

Copy link

commented May 30, 2019

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/)

@jgmac1106

This comment has been minimized.

Copy link

commented 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/)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.