Web Compatibility Data Store, API docs first

16 views
Skip to first unread message

John Whitlock

unread,
Jul 14, 2014, 9:07:11 AM7/14/14
to dev...@lists.mozilla.org
I'm going to be working on a data store for web compatibility data over the
next few months:

https://bugzilla.mozilla.org/show_bug.cgi?id=996570

I've gone through tons of wiki pages, list archives, Google docs,
etherpads, bug comments, MDN pages, etc. etc. There's a lot there.

A lot of the discussion has been around the data store, and it's a good
discussion. However, the datastore will be behind an API, so I'm starting
with an API document:

https://github.com/jwhitlock/web-platform-compat/blob/master/api.md

My goal is to flesh out this manually created documentation so that it's
most of what we'd want for the API six months from now. I find that having
a clear idea of where you're going with an API means less breaking changes
during development. I'll then identify the minimal subset needed for the
first shipping version.

This version of the doc isn't fully fleshed out. Every time I add a
feature, I end up changing a lot of other stuff. I expect lots of changes
this week. I talked a bit to Luke before the weekend, and I already know a
bunch is wrong (for example, I should eventually convert the doc from
Markdown to ReStructured Text, and the API will probably live under
developers.mozilla.org rather than a new domain). He also convinced me I
should develop in the open, rather than going dark for weeks.

Once the API doc is 90% there (mid to late July), I'll switch to
implementing the API, starting with the resources needed to implement the
tables on simple pages, such as
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/address . This
will include importing the data and implementing the KumaScript. I don't
intend to ship it to MDN - display is easy, UX for updating and creating is
hard. Once a simple display is done, we can tackle harder ones, bringing
in more of the API, and get the UX nailed down in parallel.

Please take a look at the API doc so far, and send me your feedback. At
this point, it may be better to email me or ping me on IRC (jwhitlock)
rather than pull requests and issues. I think we may wipe history when
this becomes an official mozilla repo.

John Whitlock
jwhitlock

Ali Spivak

unread,
Jul 14, 2014, 12:55:19 PM7/14/14
to John Whitlock, dev...@lists.mozilla.org
Hi John!

Welcome - we're really excited to have you here working on this project!

-ali

ali spivak
408-859-8260
asp...@mozilla.com
_______________________________________________
dev-mdn mailing list
dev...@lists.mozilla.org
https://lists.mozilla.org/listinfo/dev-mdn

Jeremie Patonnier

unread,
Jul 14, 2014, 4:16:35 PM7/14/14
to John Whitlock, dev...@lists.mozilla.org
Hi John,

This looks great :D
As I'm back from PTO, I'll take some times this week to read all of this in
deep and to provide feedback to you.

I agree that doing this in the open is the best way to work, so I'll do my
comments on that mailing list ;)

Best,
Jérémie
--
Jeremie
.............................
Web : http://jeremie.patonnier.net
Twitter : @JeremiePat <http://twitter.com/JeremiePat>

John Whitlock

unread,
Jul 15, 2014, 11:37:08 AM7/15/14
to Stephanie Hobson, dev...@lists.mozilla.org
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.

John Whitlock

unread,
Jul 15, 2014, 3:30:06 PM7/15/14
to Stephanie Hobson, dev...@lists.mozilla.org
I've added some updates to the API, prompted by Stephanie's questions.

- Added notes in the link sections, specifying the order, and if the link
can be changed to re-order or change relationships.

Browser Versions:
https://github.com/jwhitlock/web-platform-compat/blob/master/api.md#browser-versions
- Dropped next and previous links - sort order is controlled from the
browser resource
- Added release-day and retirement-day, to aid in sorting and determining
relevancy
- Changed current to status, so we can more easily identify retired,
current, and future versions

Features:
https://github.com/jwhitlock/web-platform-compat/blob/master/api.md#features
- Added canonical attribute, for resources where the name matches the code
a developer should use, such as "display: none".
- The name will be localized when canonical=false, but constant across
languages when canonical=true

Feature Sets:
https://github.com/jwhitlock/web-platform-compat/blob/master/api.md#feature-sets
- Added kuma-path, to identify the source scraped for the data
- Added canonical attribute, for resources where the name matches the code
a developer should use, such as "display".
- The name will be localized when canonical=false, but constant across
languages when canonical=true

I'm going back to reviewing MDN pages. 167 down, 955 to go. Feeling close
to complete.

John



On Tue, Jul 15, 2014 at 10:37 AM, John Whitlock <jo...@factorialfive.com>
wrote:

John Whitlock

unread,
Jul 16, 2014, 4:10:07 PM7/16/14
to Jeremie Patonnier, dev...@lists.mozilla.org
Jeremie,

Do you have a list of significant MDN pages for the interface design? I'm
looking for complex ones like CSS display, as well as ones using uncommon
features we'd like to support, such as experimental and non-standard tags.
I'm starting to assemble my own:

https://github.com/jwhitlock/web-platform-compat/blob/master/api.md#interesting-mdn-pages

John

On Mon, Jul 14, 2014 at 3:16 PM, Jeremie Patonnier <
jeremie....@gmail.com> wrote:

> Hi John,
>
> This looks great :D
> As I'm back from PTO, I'll take some times this week to read all of this
> in deep and to provide feedback to you.
>
> I agree that doing this in the open is the best way to work, so I'll do my
> comments on that mailing list ;)
>
> Best,
> Jérémie
>
>
> 2014-07-14 15:07 GMT+02:00 John Whitlock <jo...@factorialfive.com>:
>
>> I'm going to be working on a data store for web compatibility data over
>> the
>> next few months:
>>
>> https://bugzilla.mozilla.org/show_bug.cgi?id=996570
>>

Janet Swisher

unread,
Jul 16, 2014, 4:21:16 PM7/16/14
to John Whitlock, Jeremie Patonnier, dev...@lists.mozilla.org
John,

I don't know if this page is technically challenging, but it's kind of
the worst case scenario content-wise, because of the number of features
and their variety of levels of browser support:
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Input#Browser_compatibility
> _______________________________________________
> dev-mdn mailing list
> dev...@lists.mozilla.org
> https://lists.mozilla.org/listinfo/dev-mdn

--
Janet Swisher <mailto:jREMOVE...@mozilla.com>
Mozilla Developer Network <https://developer.mozilla.org>
Developer Relations Community Organizer

Florian Scholz

unread,
Jul 16, 2014, 4:46:20 PM7/16/14
to dev...@lists.mozilla.org
This one is a beast - but don't give up yet!

Long time ago, I opened bugs and proposed that this page should have sub
pages for each input type at some point. I doubt we want to have such
monster tables for a whole API. Instead more sub pages for each feature
of this API are needed. Also note, that each of these input types can
have details on implementations e.g. on mobile vs. desktop, too, which
is impossible to add to this already crowded table and notes section.

So, yes this has a lot of features in the table right now, but it is
hopefully going to be refactored content-wise and will lead to smaller
and saner compat tables on multiple pages ideally.

Example from other parts of the documentation:
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array
This does not list all JS Array methods, but instead sub pages are
talking about it in detail.

Florian

--
Florian Scholz
Technical Writer
Mozilla Developer Network
t: @floscholz

Jeremie Patonnier

unread,
Jul 18, 2014, 10:00:17 AM7/18/14
to John Whitlock, dev...@lists.mozilla.org
Hi john!

Actually, I have a huge amount of comments. I can write a very long e-mail
to raise all of them but it could be maybe a bit more efficient to set up a
Vidyo meeting to discuss them directly (a public meeting of course ;)

What do you think?

++
Jeremie


2014-07-14 15:07 GMT+02:00 John Whitlock <jo...@factorialfive.com>:

> I'm going to be working on a data store for web compatibility data over the
> next few months:
>
> https://bugzilla.mozilla.org/show_bug.cgi?id=996570
>

Luke Crouch

unread,
Jul 18, 2014, 10:56:55 AM7/18/14
to Jeremie Patonnier, John Whitlock, dev...@lists.mozilla.org
+1 if we uplift the comments from Vidyo meeting to another online
artifact (pull request against the api.md?) and link to it from this thread.

-L
Q: Why is this email five sentences or less?
A: http://five.sentenc.es

John Whitlock

unread,
Jul 18, 2014, 3:24:37 PM7/18/14
to Luke Crouch, dev...@lists.mozilla.org, Jeremie Patonnier
I had a two-hour meeting w/ Jeremie, and a 1/2 hour with Holly. I have
some answers, and for other things I'm more confused but in a deeper, more
meaningful way.

Jeremie has offered to type up the notes from the meeting. I'll make some
API changes and report a summary here. Expect both around Monday.

I think next week I'll ask some questions on IRC to get a first-pass
consensus on big issues, then convert the API doc to another format
(etherpad? google docs?) for line-by-line arguments.


On Fri, Jul 18, 2014 at 9:56 AM, Luke Crouch <lcr...@mozilla.com> wrote:

> +1 if we uplift the comments from Vidyo meeting to another online
> artifact (pull request against the api.md?) and link to it from this
> thread.
>
> -L
>
>
> On 7/18/14 9:00 AM, Jeremie Patonnier wrote:
>
> Hi john!
>
> Actually, I have a huge amount of comments. I can write a very long e-mail
> to raise all of them but it could be maybe a bit more efficient to set up a
> Vidyo meeting to discuss them directly (a public meeting of course ;)
>
> What do you think?
>
> ++
> Jeremie
>
>
> 2014-07-14 15:07 GMT+02:00 John Whitlock <jo...@factorialfive.com> <jo...@factorialfive.com>:
>
>
> > I'm going to be working on a data store for web compatibility data over the> next few months:>> https://bugzilla.mozilla.org/show_bug.cgi?id=996570>> I've gone through tons of wiki pages, list archives, Google docs,> etherpads, bug comments, MDN pages, etc. etc. There's a lot there.>> A lot of the discussion has been around the data store, and it's a good> discussion. However, the datastore will be behind an API, so I'm starting> with an API document:>> https://github.com/jwhitlock/web-platform-compat/blob/master/api.md>> My goal is to flesh out this manually created documentation so that it's> most of what we'd want for the API six months from now. I find that having> a clear idea of where you're going with an API means less breaking changes> during development. I'll then identify the minimal subset needed for the> first shipping version.>> This version of the doc isn't fully fleshed out. Every time I add a> feature, I end up changing a lot of other stuff. I expect lots of changes> this week. I talked a bit to Luke before the weekend, and I already know a> bunch is wrong (for example, I should eventually convert the doc from> Markdown to ReStructured Text, and the API will probably live under> developers.mozilla.org rather than a new domain). He also convinced me I> should develop in the open, rather than going dark for weeks.>> Once the API doc is 90% there (mid to late July), I'll switch to> implementing the API, starting with the resources needed to implement the> tables on simple pages, such as> https://developer.mozilla.org/en-US/docs/Web/HTML/Element/address . This> will include importing the data and implementing the KumaScript. I don't> intend to ship it to MDN - display is easy, UX for updating and creating is> hard. Once a simple display is done, we can tackle harder ones, bringing> in more of the API, and get the UX nailed down in parallel.>> Please take a look at the API doc so far, and send me your feedback. At> this point, it may be better to email me or ping me on IRC (jwhitlock)> rather than pull requests and issues. I think we may wipe history when> this becomes an official mozilla repo.>> John Whitlock> jwhitlock> _______________________________________________> dev-mdn mailing list> dev...@lists.mozilla.org> https://lists.mozilla.org/listinfo/dev-mdn>
>
> --
> Jeremie
> .............................
> Web : http://jeremie.patonnier.net
>
> Twitter : @JeremiePat <http://twitter.com/JeremiePat> <http://twitter.com/JeremiePat>
>
> _______________________________________________
> dev-mdn mailing listdev-mdn@lists.mozilla.orghttps://lists.mozilla.org/listinfo/dev-mdn

Luke Crouch

unread,
Jul 18, 2014, 5:52:44 PM7/18/14
to John Whitlock, dev...@lists.mozilla.org, Jeremie Patonnier

On 7/18/14 2:24 PM, John Whitlock wrote:
> I had a two-hour meeting w/ Jeremie, and a 1/2 hour with Holly. I
> have some answers, and for other things I'm more confused but in a
> deeper, more meaningful way.
>
> Jeremie has offered to type up the notes from the meeting. I'll make
> some API changes and report a summary here. Expect both around Monday.
>
> I think next week I'll ask some questions on IRC to get a first-pass
> consensus on big issues, then convert the API doc to another format
> (etherpad? google docs?) for line-by-line arguments.

Can we try a README.rst in the start of the github repository? We can
make line-by-line comments in pull requests or issues.

-L

>
>
> On Fri, Jul 18, 2014 at 9:56 AM, Luke Crouch <lcr...@mozilla.com
> <mailto:lcr...@mozilla.com>> wrote:
>
> +1 if we uplift the comments from Vidyo meeting to another online
> artifact (pull request against the api.md <http://api.md>?) and
> link to it from this thread.
>
> -L
>
>
> On 7/18/14 9:00 AM, Jeremie Patonnier wrote:
>> Hi john!
>>
>> Actually, I have a huge amount of comments. I can write a very long e-mail
>> to raise all of them but it could be maybe a bit more efficient to set up a
>> Vidyo meeting to discuss them directly (a public meeting of course ;)
>>
>> What do you think?
>>
>> ++
>> Jeremie
>>
>>
>> 2014-07-14 15:07 GMT+02:00 John Whitlock<jo...@factorialfive.com> <mailto:jo...@factorialfive.com>:
>>
>>> >I'm going to be working on a data store for web compatibility data over the
>>> >next few months:
>>> >
>>> >https://bugzilla.mozilla.org/show_bug.cgi?id=996570
>>> >
>>> >I've gone through tons of wiki pages, list archives, Google docs,
>>> >etherpads, bug comments, MDN pages, etc. etc. There's a lot there.
>>> >
>>> >A lot of the discussion has been around the data store, and it's a good
>>> >discussion. However, the datastore will be behind an API, so I'm starting
>>> >with an API document:
>>> >
>>> >https://github.com/jwhitlock/web-platform-compat/blob/master/api.md
>>> >
>>> >My goal is to flesh out this manually created documentation so that it's
>>> >most of what we'd want for the API six months from now. I find that having
>>> >a clear idea of where you're going with an API means less breaking changes
>>> >during development. I'll then identify the minimal subset needed for the
>>> >first shipping version.
>>> >
>>> >This version of the doc isn't fully fleshed out. Every time I add a
>>> >feature, I end up changing a lot of other stuff. I expect lots of changes
>>> >this week. I talked a bit to Luke before the weekend, and I already know a
>>> >bunch is wrong (for example, I should eventually convert the doc from
>>> >Markdown to ReStructured Text, and the API will probably live under
>>> >developers.mozilla.org <http://developers.mozilla.org> rather than a new domain). He also convinced me I
>>> >should develop in the open, rather than going dark for weeks.
>>> >
>>> >Once the API doc is 90% there (mid to late July), I'll switch to
>>> >implementing the API, starting with the resources needed to implement the
>>> >tables on simple pages, such as
>>> >https://developer.mozilla.org/en-US/docs/Web/HTML/Element/address . This
>>> >will include importing the data and implementing the KumaScript. I don't
>>> >intend to ship it to MDN - display is easy, UX for updating and creating is
>>> >hard. Once a simple display is done, we can tackle harder ones, bringing
>>> >in more of the API, and get the UX nailed down in parallel.
>>> >
>>> >Please take a look at the API doc so far, and send me your feedback. At
>>> >this point, it may be better to email me or ping me on IRC (jwhitlock)
>>> >rather than pull requests and issues. I think we may wipe history when
>>> >this becomes an official mozilla repo.
>>> >
>>> >John Whitlock
>>> >jwhitlock
>>> >_______________________________________________
>>> >dev-mdn mailing list
>>> >dev...@lists.mozilla.org <mailto:dev...@lists.mozilla.org>
>>> >https://lists.mozilla.org/listinfo/dev-mdn
>>> >
>> -- Jeremie ............................. Web :
>> http://jeremie.patonnier.net
>> Twitter : @JeremiePat <http://twitter.com/JeremiePat>
>> <http://twitter.com/JeremiePat>
>> _______________________________________________ dev-mdn mailing
>> list dev...@lists.mozilla.org <mailto:dev...@lists.mozilla.org>

John Whitlock

unread,
Jul 21, 2014, 9:00:14 AM7/21/14
to Luke Crouch, dev...@lists.mozilla.org, Jeremie Patonnier
I don't understand. Do you mean:

* Convert README.md to README.rst?
* Move api.md to README.rst?
* Something else?

Luke Crouch

unread,
Jul 21, 2014, 9:47:00 AM7/21/14
to John Whitlock, dev...@lists.mozilla.org, Jeremie Patonnier
On 7/21/14 8:00 AM, John Whitlock wrote:
> I don't understand. Do you mean:
>
> * Convert README.md to README.rst?
> * Move api.md <http://api.md> to README.rst?

Convert to README.rst, and add a docs/api.rst so we can do some
README-driven development. [1] Maybe:

1. Put the overview, entrypoints, and "Issues to Resolve" sections into
a README.rst for the main repo, with a link to ...
2. The API docs in docs/api.rst

That way, we can send pull requests against api.rst to propose and
discuss API changes.

3. When some API code is live on MDN, add a link from README.rst to live
API docs (django-rest-swagger?)


-L


[1] http://tom.preston-werner.com/2010/08/23/readme-driven-development.html

John Whitlock

unread,
Jul 22, 2014, 5:36:05 PM7/22/14
to Luke Crouch, dev...@lists.mozilla.org, Jeremie Patonnier
Luke,

The generated docs, fit for linking, are at:

http://web-platform-compat.readthedocs.org/en/latest/

The conversion was done in one commit on master, if you want to try a
per-line comment:

https://github.com/jwhitlock/web-platform-compat/commit/62f74355f2c046d406d8bc616c82d27584aee272

The draft API is split over several files. All the "issues to resolve" are
in the issues doc:

https://github.com/jwhitlock/web-platform-compat/tree/master/docs/draft
https://github.com/jwhitlock/web-platform-compat/blob/master/docs/draft/issues.rst

And, if you want to comment with issues and pull requests, we can do that
as well:

https://github.com/jwhitlock/web-platform-compat/issues

If someone has a preferred way to collaborate, please let me know.

John




On Mon, Jul 21, 2014 at 8:47 AM, Luke Crouch <lcr...@mozilla.com> wrote:

> On 7/21/14 8:00 AM, John Whitlock wrote:
>
> I don't understand. Do you mean:
>
> * Convert README.md to README.rst?
> * Move api.md to README.rst?
Reply all
Reply to author
Forward
0 new messages