Stephanie,
Good questions. My short answer is that we'll spend a little time
designing a better MDN, ship something that looks identical to the current
MDN, and work a little each day to get to the better MDN. Much longer
answers follow.
Github doesn't include a table of contents, but you can link to sections.
The "Issues to Resolve ..." section is way at the end of the doc:
https://github.com/jwhitlock/web-platform-compat/blob/master/api.md#issues-to-resolve-before-code
*Q1: In features there is no way to get the code's name for the feature.
The thing we would actually want to write in the code. In your example this
is "contain". Localizing the property for search and communication purposes
makes sense, but the reader still needs to know what to actually type for
the browsers. I'm going to call this the "canonical" name for the rest of
this email.*
https://github.com/jwhitlock/web-platform-compat/blob/master/api.md#features
A1: There are two ways to think of features:
#1 The smallest unit of functionality from a specification
#2 A row in a Browser Compatibility table on an MDN page.
I want to use definition #1, but I think it is too much work to do. I
think we'll ship #2, and can evolve toward #1 on a page-by-page basis.
For example, consider the display CSS property. I think the Syntax table
uses definition 1:
https://developer.mozilla.org/en-US/docs/Web/CSS/display#Syntax
In this case, the properties would be "CSS property display with value
none", "CSS property display with value inline", etc. The identifiers
could fit a pattern like "CSS property: display: none", or
"css-property-display-none", in slug format. Translations would be less of
an issue as well; "display: none" is pure CSS, and so it's the same in
every language.
However, the Browser Compatibility table uses definition #2:
https://developer.mozilla.org/en-US/docs/Web/CSS/display#Browser_compatibility
The first row is "none, inline and block". This combines three of the four
CSS Level 1 display values (list-item is it's own, because IE 4 doesn't
support it). This makes sense for a manually-created table - why duplicate
rows when browser support will be the same for all three? A little
convenience now means that you have to localize the property name, however,
since 'and' and conjunctive phrases are language-specific.
My solution is to get the data into the data store in the current row
format (#2), but allow adding and changing properties to eventually get
them into canonical format (#1). Maybe "feature" should include a
"canonical" boolean flag, to identify features where the name is also what
a developer would use in their CSS or HTML. The features with canonical:
true would be displayed in a fixed-width font (markup <code>display:
none</code>), and would not be translated. The features that have
canonical:false" could be displayed in a "pages to fix" queries, and be
fixed in priority order.
The MDN page editor may occasionally need to refer to a feature as well.
The slug is an attempt to make a human-friendly identifier, that could be
used in KumaScript (i.e.
BrowserSupportForFeature('css-background-size-contain')). I would expect
users to pull slugs from existing MDN source or from some look-up table.
*Q2: It's not totally clear to me from the data structure how
properties/attributes would be handled. It seems like a feature set, if
that is true we need an option to have a canonical name for feature sets as
well. In your example this is "background-size".*
https://github.com/jwhitlock/web-platform-compat/blob/master/api.md#feature-sets
A2: Feature sets have two possible definitions:
#1 A collection of features, such as all the values for CSS property
display, arranged in a hierarchy of technologies, such as "Web
Technologies" -> "CSS" -> "CSS properties" -> "CSS property display"
#2 A page on MDN.
Similar to features, I'd like to go with #1, but I think we're going to
ship #2.
For the first version, I think there will be a 1:1 relationship between MDN
pages and feature sets, and the hierarchy will follow the the MDN
page hierarchy. For example, these two pages will be siblings:
https://developer.mozilla.org/en-US/docs/Web/CSS/:default
https://developer.mozilla.org/en-US/docs/Web/CSS/border-bottom-left-radius
The hierarchy will be something like:
"Web" -> "CSS" -> ":default"
"Web" -> "CSS" -> "border-bottom-left-radius"
This is flatter than some might choose, and many pages will have feature
sets with a single feature. The feature set will get an ID as well as a
slug, and I expect the KumaScript to use the slug, i.e.
SpecificationsForFeatureSet('css-border-bottom-left-radius')
Once the current data is in the data store, we can then move toward
definition #1, with a hierarchy such as:
"Web" -> "CSS" -> "CSS properties" -> "border-bottom-left-radius"
"Web" -> "CSS" -> "CSS pseudo-classes" -> ":default"
or even:
"Web" -> "CSS" -> "CSS properties" -> "CSS Borders" -> "CSS Border Radius"
-> "border-bottom-left-radius"
If we have the bandwidth, we can play with the feature set hierarchy before
shipping, in a Google doc or similar tech. I'm working from the
WebPlatform.org scraping of MDN, which identified 1194 pages with compat
data, to give you a sense of the size of the problem. If people have the
bandwidth and desire to work on the hierarchy, speak up.
Feature sets could grow a "kuma-path" attribute, to designate the page that
the feature set was originally scraped from.
I'm not sure if there is a feature set equivalent of the 'canonical' flag,
either to say "this is what a dev should type" or "an MDN editor has
approved this name". We could add one, if it makes sense for workflow, or
just dump the hierarchy to an MDN page or Google Doc and delete lines as an
editor approves them.
*Q3: Some feature sets will have multiple parents. (display would be part
of the Flex Box feature set as well as the Table Layout feature set) (href
would be part of <link> and <a>) (cover would be a value for the
background-size as well as the background properties)*
A3: For shipping, I'll defer to the current MDN feature hierarchy -
"display" appears under "CSS", under "Web":
https://developer.mozilla.org/en-US/docs/Web/CSS/display
In this hierarchy, there is nothing to distinguish traditional values
(none, inline, block) from flex box values (flex, inline-flex) from table
values (table, table-cell, table-column). They all get put in the same bag.
So, how do we get to logical ordering?
One way would be to break up the CSS display property into a feature set:
* Feature Set "CSS:display" is the parent of Feature Set "CSS:display:CSS1
Values", "CSS:display:CSS2.1 Values", "CSS:display:Flexible Box Values",
etc, and has no Features
* Feature Set "CSS:display:CSS1 Values" has no Feature Sets, but Features
"display: none", "display:block", "display: inline", and "display:
list-item",
* Feature Set "CSS:display:CSS2.1 Values" has Feature Sets
"CSS:display:CSS2.1 Values:Table Layout Values" and one Feature "display:
inline-block"
* Feature Set "CSS:display:Flexible Box Values" has no Feature Sets, but
Features "display: flex" and "display: inline-flex"
Or, as a graph:
[image: Inline image 1]
And so on.
80% of this grouping could also be accomplished by grouping by
specification, but that requires an ordering of specifications, which might
be just as difficult. "display: none" appears in CSS1, CSS2.1, CSS Basic
Box, etc. etc., so we'd have to have a way to say "this appears in all
these specs, but this is the one that is important for grouping and
ordering". So, I think the manually-created hierarchy is actually easier.
CSS display is one of the more complicated MDN pages, but you can see why I
don't want to delay shipping for 1,000+ grouping decisions. Instead, I
want an API and tools for performing this cleanup post shipping on a
page-by-page basis.
As for other values, I find it easier to think of the feature as "CSS
property display with value none", or "display: none" in shorthand, rather
than "the value none". This means that your other examples become "<link
href...>" and "<a href=...>", "background-size: cover" and "background:
cover". This will result in an unfortunate level of duplicate content - a
browser version will have to list support for both properties, and a human
will have to keep them in sync. I'm not sure if we can say "this is
exactly the same as this, with the same browser support, but with a
different name". I'd like to hear from those with more web tech experience
than me.
*Q4. Do we have a way to represent the correct order for properties in
short hand? Or to support shorthand at all?*
A4. At the feature-set level, features are ordered:
https://github.com/jwhitlock/web-platform-compat/blob/master/api.md#feature-sets
{
"feature-sets": {
"id": "373",
"slug": "css-background-size",
"name": {
"en": "background-size"
},
"links": {
"features": ["275", "276", "277"],
"specification-sections": [],
...
}
},
The code that generates a compatibility table should make feature "275" the
first data row, "276" the second, etc. If the features list is PUT back in
a different order, that order will be preserved. Initial order will be the
order as displayed on MDN. I'll make that clearer in the docs.
Other lists, such as specification-sections, are also ordered.
MPTT enforces sibling order among feature sets. I'll have to think if a
PUT will adequately model a change in ordering, but I suspect it will work.
I'm hand-waving the significant UX challenge of designing an interface that
makes it clear that row order can be changed, and the KumaScript code to
send this change back to the API.
*Q5. Does the system allow for future versions of the browsers to be
documented? It seems like it will but it wasn't clear from any of your
examples. *
A5. This was an oversight - I wasn't mindful that there was a lot known
about future versions of Firefox and other browsers. I think browser
versions should grow a "release-date" and a "retirement-date", to replace
the "current" flag. It makes sense to add a "future" flag, so that the
"release-date" is interpreted as a planned release date rather than a
historical fact (in case release delays occur).
Sorry for the wordy answers, but this stuff is complex,
John
On Mon, Jul 14, 2014 at 3:01 PM, Stephanie Hobson <
sho...@mozilla.com>
wrote:
> Hi John,
>
> Really excited to see this moving forward :)
>
> I'm sort of glimpsing bits of this project as it flies past to forgive me
> if I am suggesting something contrary to requirements document somewhere :)
>
> I had a look over
https://github.com/jwhitlock/web-platform-compat/blob/
> master/api.md (which is incredibly through!) and a couple things stuck
> out to me as a front-end dev. You've already identified some of them in
> "unresolved issues" section:
>
> - In features there is no way to get the code's name for the feature. The
> thing we would actually want to write in the code. In your example this is
> "contain". Localizing the property for search and communication purposes
> makes sense, but the reader still needs to know what to actually type for
> the browsers. I'm going to call this the "canonical" name for the rest of
> this email.
> - It's not totally clear to me from the data structure how
> properties/attributes would be handled. It seems like a feature set, if
> that is true we need an option to have a canonical name for feature sets as
> well. In your example this is "background-size".
> - Some feature sets will have multiple parents. (display would be part of
> the Flex Box feature set as well as the Table Layout feature set) (href
> would be part of <link> and <a>) (cover would be a value for the
> background-size as well as the background properties)
> - Do we have a way to represent the correct order for properties in short
> hand? Or to support shorthand at all?
> - Does the system allow for future versions of the browsers to be
> documented? It seems like it will but it wasn't clear from any of your
> examples.
>
> Thanks,
> Stephanie.