Closed Bug 1102508 Opened 10 years ago Closed 9 years ago

Add to syntax boxes a link to an article explaining how to interpret them

Categories

(developer.mozilla.org Graveyard :: Design, enhancement)

x86
macOS
enhancement
Not set
normal

Tracking

(Not tracked)

RESOLVED FIXED

People

(Reporter: shobson, Assigned: shobson)

Details

Attachments

(3 files)

Attached image Syntax box - current
In places where an article contains syntax it would be helpful to users to link to an article explaining how to read syntax.

For example: https://developer.mozilla.org/en-US/docs/Web/CSS/transform

This will help new users understand our content and how the technology they're trying to use works.

= Option 1

Add a link to the syntax article whenever a <pre> with a class of .syntax and .twopartsyntaxbox is detected.

Pros:
- it would appear only on :hover or :focus, not getting in the way of current content
- it would apply immediately to all places we have syntax currently

Cons:
- not visible, does not encourage users to engage
- we can use a combination of things to guess at what language the syntax is for, but we will be guess wrong some times (those places could be corrected manually)


= Option 2

Prevent prism from styling <pre>s with a class of .syntaxbox and .twopartsyntaxbox which would allow links to appear in this content.

When used this macro https://developer.mozilla.org/en-US/docs/Template:csssyntax generates links and tooltips explaining how each part of the syntax works however those links are being stripped out when prism.js formats them

Pros:
- each part of the syntax is explained
- hit area is very small on mobile, tool tips don't display on mobile

Cons:
- these links only appear when the macro has been used to generate the syntax and there are many places where it has not
- no prism.js formatting on syntax (this would only effect a few small places because most syntax boxes do not have a prism brush being defined so they are being styled the fallback - HTML, but we have almost no HTML in syntax boxes)

= Questions

I'd like to implement option #1 immediately, is that okay?

Do we want to also implement option #2? I think so.

= 

Attachments will be added showing both these options.

This hasn't been identified as a priority so I can't do too much additional work on it but both of these options can be achieved in a morning ;)

Thanks to :teoli and :sheppy for providing me with background info to get to this point.
Flags: needinfo?(jypenator)
Flags: needinfo?(eshepherd)
Assignee: nobody → shobson
Severity: normal → enhancement
Component: General → Design
Jean-Yves -- IIRC you were going to write up an overview piece that could be used for this purpose. Do I remember that correctoy, or am I hallucinating? :)
Flags: needinfo?(eshepherd)
Flags: needinfo?(jypenator)
Summary: Link syntax to articles on how to read syntax → Add to syntax boxes a link to an article explaining how to interpret them
I identified this article as the place to link CSS syntax: https://developer.mozilla.org/en-US/docs/Web/CSS/Value_definition_syntax Which might be the one sheppy is thinking of.

I've also identified 2 other kinds of syntax we could add the link to (JavaScript and HTML) but those would need to go to other articles which I don't think exist.
It is the right article that the different symbol links to.

Btw, to answer the question, we should do 1 and 2. 

But I don't think there is a formal grammar used in JS and HTML so there is nothing to point to.
(In reply to Stephanie Hobson [:shobson] from comment #4)
> I identified this article as the place to link CSS syntax:
> https://developer.mozilla.org/en-US/docs/Web/CSS/Value_definition_syntax
> Which might be the one sheppy is thinking of.

Yes, that's the page you should be linking to for CSS pages.

> I've also identified 2 other kinds of syntax we could add the link to
> (JavaScript and HTML) but those would need to go to other articles which I
> don't think exist.

They don't; our "syntax" boxes for JavaScript are really just examples, and on HTML pages, we don't really present a syntax at all. We just present the name of the element, then a list of the attributes and their possible values, with notes about details like when one attribute requires the use of another, etc.

It may maek sense to move to a formal syntax presentation for either or both of JS and HTML, but for now, let's just get this bug wrapped for CSS.
Commits pushed to master at https://github.com/mozilla/kuma

https://github.com/mozilla/kuma/commit/18b07e6ccd6002efb8c81133b2cfedaf9a5b1c64
Fix Bug 1102508: Link Syntax to Syntax Help Article

Added javascript to detect syntaxbox and twopartsyntaxbox and create a link to help articles based on if there is a CSS class identifying the language, falling back to the language the section is in if there is not.

Added CSS to style the link.

https://github.com/mozilla/kuma/commit/a74d74840cc2a015b839b3cb206f8cb89b47fd40
Fix Bug 1102508: Link Syntax to Syntax Help Article

Prevent prism from styling syntaxbox and twopartysyntaxbox so that we can link the syntax to articles explaining it.

Update styles so they're still styled correctly without prism.

https://github.com/mozilla/kuma/commit/36ffa14f771a63c921dc7d6daf34fff1735db20e
Merge pull request #2953 from stephaniehobson/BUG-1102508-syntax

Fix Bug 1102508: Link syntaxboxes to Syntax Help Article
Status: NEW → RESOLVED
Closed: 9 years ago
Resolution: --- → FIXED
Product: developer.mozilla.org → developer.mozilla.org Graveyard
You need to log in before you can comment on or make changes to this bug.

Attachment

General

Created:
Updated:
Size: