839345 - Better highlight MDN documentation for the technologies that demos use

Status: RESOLVED WONTFIX

(developer.mozilla.org Graveyard :: Demo Studio / Dev Derby, enhancement)

Description

[John Karahalis [:openjck]]

What problems would this solve?
===============================
People who browse the Demo Studio are interested in web development. We should use our existing resources to help them understand how the demos on the site are created.

Who would use this?
===================
Anyone who browses through demos.

What would users see?
=====================
Maybe something like a section called "How this Demo was made". This section could link to the /learn page (not everyone who browses the Demo Studio is an expert) as well as MDN documentation for the technologies used in the demo.

What would users do? What would happen as a result?
===================================================
Users would click the links and read the corresponding MDN articles that open.

Is there anything else we should know?
======================================
Demo authors can already "tag" their demos as using certain technologies. The list is a little out of date, but if we update it we might be able to use that information rather than feature detection.

Comment 1

[Les Orchard [:lorchard]]

Really, this is what the technology tags on demos are for. Actually divining what technologies were used in a demo would be very difficult.

When you say the list is out of date, do you have a notion as to what updates are needed?

Comment 2

[John Karahalis [:openjck]]

(In reply to Les Orchard [:lorchard] from comment #1)
> Really, this is what the technology tags on demos are for.

Good point. My comment about obsolete technologies applies here too.

https://bugzilla.mozilla.org/show_bug.cgi?id=746817#c3

Worth noting one thing -- clicking on a technology tag does link to the corresponding MDN article, but Robert Nyman (who requested this feature) missed that. We should take another look at how Demo Studio entries refer users to corresponding documentation.

> When you say the list is out of date, do you have a notion as to what
> updates are needed?

Sure. Camera API is not in the list. Same with Fullscreen API, device Orientation, and a handful of other important new technologies. We have "Device" but that's not as useful for linking to documentation.

Comment 3

[Les Orchard [:lorchard]]

Need some more detail on this bug - I'm not sure what the concrete task / plan is.

Current implementation of the demo detail template has something like "Built using HTML5, IndexedDB, Offline Support". Each term links to a tag listing more demos under that tech, and there's a "Learn More" sidebar with links to other docs.

Does that implementation need changing - and if so, how exactly?

We have a list of technologies, starting here in the code for tag descriptions:

https://github.com/mozilla/kuma/blob/master/apps/demos/__init__.py#L329

Does that list need changing - and if so, how exactly?

Comment 4

[John Karahalis [:openjck]]

(In reply to Les Orchard [:lorchard] from comment #3)
> Need some more detail on this bug - I'm not sure what the concrete task /
> plan is.

This has not passed the "Design" phase yet, so it is not ready for development. I neglected to mention in our meeting on Friday that the a specification (comment 0) is not necessarily the be-all-end-all for how a feature should look and behave. It is instead just enough information for a design team to put something together. That design might be exactly what the user requested, or it might be something different that solves the same basic problem.

As far as this request goes, my idea about a "How this Demo was made" box is just an idea. We might end up solving the same problem with a different design.

> Current implementation of the demo detail template has something like "Built
> using HTML5, IndexedDB, Offline Support". Each term links to a tag listing
> more demos under that tech, and there's a "Learn More" sidebar with links to
> other docs.
> 
> Does that implementation need changing - and if so, how exactly?

I think it does, because Rob Nyman did not realize that the Dev Derby refers to MDN documentation at all. But it might just be him. Another question to be sorted out in the "Design" phase.

> We have a list of technologies, starting here in the code for tag
> descriptions:
> 
> https://github.com/mozilla/kuma/blob/master/apps/demos/__init__.py#L329
> 
> Does that list need changing - and if so, how exactly?

Remains to be determined. If we use that list to let users specify the technologies they are using -- probably. If we use feature detection (again, not saying we necessarily should) then we would still probably want to update that list, but for different reasons and as part of a different effort.

Comment 5

[John Karahalis [:openjck]]

Anyway, with all that said I have pulled this into the design phase so we can start answering these questions.

We are low on design resources at the moment, but I will try to take on this work for now. At some point (looking to be fairly soon), we should have some people with more expertise to drive this phase.

Comment 6

[David Walsh :davidwalsh]

I'm with Les, we should (1) update the tag list and (2) associate the tag list items with URLs to the technology's page on MDN.  IMO, there's no way we can generate an accurate list of technologies used by scanning the code.  For example, if jQuery were included, we'd not know which technologies within it that were used.

Comment 7

[karabajic]

For example, WebRTC demos will soon be posted and there are 17 articles in webRTC category on mozilla hacks blog. 

Is WebRTC a tag or is it a category/subcategory? Is it RTC-real time communication category or if a subcategory, child element of web browser technologies, javascript, communication, HTML5 category and so on.

With close to 100 categories on mozilla hacks blog, categorization is looking more and more like spaghetti code,  a pejorative term for source code that has a complex and tangled control structure, and in mozilla hacks blog's case, tangled taxonomy structure.  

Categories are meant for broad grouping as general topics or the table of contents used to assist readers in finding the right type of content on your site. Categories are hierarchical, so you can define sub-categories. (none at mozilla hacks blog) 

Tags are meant to describe specific details of your posts or site’s index words. They are the micro-data that you can use to micro-categorize your content. Tags are not hierarchical. (tags should be admin/editor defined and user/contributor would not be allowed to create additional tags, only check them through multi-select option window) 

There is also an argument that "Category Hierarchies Are Meaningless" making tags and categories essentially the same thing, evident on Mozilla Hacks blog with no tagging features.  

This is the most important aspect for successful mdn redesign effort and needs to be addressed as a top level priority, not only for MDN but the mozilla as whole. It is not a question of only integrating mozilla hacks and MDN into unified experience, but unifying the whole system of information silos throughout mozilla's information ecosystem. 

Having some previous experience working on 60000 pages City of Toronto website information architecture and taxonomy audit, I would be willing to undertake an effort and work together on this rather complex issue. 

Before any visual redesign/flows/mockups are done, audit of existing taxonomy structure is needed and integrated information management approach consensus/collaboration from other groups required. I understand this is rather ambitious task, but I am willing to work along and give it a try if there is feeling this would be beneficial to redesign effort. Let me know.

Comment 8

[ali spivak]

Demo Studio is being removed from MDN and archived as of end January 2016