- From: Amelia Bellamy-Royds <amelia.bellamy.royds@gmail.com>
- Date: Tue, 16 Sep 2014 12:40:06 -0600
- To: List WebPlatform public <public-webplatform@w3.org>
- Message-ID: <CAFDDJ7xOjg1TEdZgB+2YU0-O2xsAwi-sR0421p9HDWsN6v2XEw@mail.gmail.com>
WebPlatform Docs, weekly telcom meeting Chaired by Doug Schepers (shepazu) In attendance: - Amelia Bellamy-Royds (AmeliaBR, scribing) - Jen Simmons (jensimmons) - Eliot Graff (eliot) TOPICS: update on ongoing projects, what's next for compatibility tables Starting a telcon, with an almost-quorum of 4 shepazu (chairing): schedule -- will be away later in the month, vacation plus speaking in Sao Paolo; original plan included a DocSprint, but the local organization has changed over and it looks like it will be more informal ...recap from last week: we discussed options for a "mini DocSprint", getting people introduced to the concept, some editing, encouraging translation into Portuguese ...we really want translations for languages in areas where English is not a significant second language eliot: Russian would be another shepazu: translations are something we should put focus on, have a strategy around it ... last week we also talked about the HTML5 recommendation status announcement, considered whether we could have comprehensive HTML docs by then, but that doesn't seem likely. Amelia suggested that we prep things so we are ready for new contributors on HTML, and capitalize on the announcement to encourage people to document the now-defined standard. eliot: Our goal (as organizers) has not been to do the documentation, but to create the infrastructure for the community to write docs, so that seems like a good strategy shepazu: By that time, in less than a few weeks, we should have a functional annotation system. ... we want people to go through the specs, identify areas that need documentation AmeliaBR: Clarify: annotations for the specs or annotations for webplatform docs? shepazu: they are one and the same, ...we've been working (with renoirb) and the Hypothesis team on this, and there will be a way for you to search all annotations everywhere; e.g., you could search "SVG" and "needs example" ... the annotation system will be for our pages, on the wiki, but there will also be a script on certain W3 specifications, that will be connected to our server. ... Instead of sending an email, they will make an account on our server and create a note there which will tie our docs back into the W3 specs. ... It also lets people leave comments on specifications, about what should be documented on webplatform docs. ... e.g., could identify a specific sentence or detail about an element, that comment would show up on the webplatform page about that element as well as on the specs. Then when the documentation is taken care of, that comment could be closed in both places. ... and vice versa: if someone leaves a comment on our docs, e.g., that something is really confusing, that something should be changed in the actual specs, that comment can easily be connected back to the actual specs. ...we're hoping to get that virtuous cycle going. ... Amelia, what else did we do last week? AmeliaBR: renoirb gave us an update on compatibility tables, he also sent some updates to the email list since then shepazu: now we have to decide if we want to work on the caniuse data, or focus on the W3 test data AmeliaBR: I'd recommend focusing energy on the test suite, rather than spending a lot of time on caniuse.com jensimmons: but what is the test data like? I use caniuse all the time, that's existing, reliability data <+AmeliaBR> http://test.csswg.org/harness/ <@shepazu> https://github.com/w3c/web-platform-tests jensimmons: that link, is that the tests, or is that the data? it's a terrible user interface shepazu: it is a terrible user interface, there's lots of data, but it's not easily available jensimmons: well that could be the differentiator, where we could make a difference eliot: the data is there, but it's not available in a universal way. Also, while it's great to have tests connected to the specs, it's nice to have a more top-level practical synthesis, which is what caniuse does well AmeliaBR: In a way, the caniuse data complements the MDN data, because it focuses on the top-level, big concepts, while MDN is more element-by-element, attribute-by-attribute. So if we can integrate that easily in our structure, that would be beneficial to have compat data on top-level pages shepazu: I'm kind of on the fence. We would have to massage the caniuse data a lot; but, when we adapted the MDN data, we did use codes and info similar to what caniuse uses, for e.g. whether polyfill or prefix is required. ...but we would have to work on the mapping of their data to our categorizations ...and it's not just the data, it's whether we would add anything as far as making it easier to access jensimmons: is the plan to merge all the data into one super data set, or are we going to be displaying this side by side? shepazu: no, I think we'd have to decide, for any given page, which data to use. Since the caniuse data is based on some testing, it would probably replace the MDN data, if there was a one-to-one match. Then later, if we have the W3 data, that could replace jensimmons: But we also have to be careful, e.g. tests might not catch all the little nuances, where caniuse has notes or explanations that someone has gone in and added AmeliaBR: The difference is that W3 tests try to represent that with multiple tests, each of which catches a different situation or edge case, rather than summing it up with one measurement. But we'd have to decide how to display that information. jensimmons: The other great thing about caniuse is that they clearly display the versions of web browsers, which is much more relevant than just saying something "is supported in Chrome" shepazu: that's what I was saying, it's not just the data, it's how they display it, which caniuse does so well ... we really want to get away from the idea of just being another MDN. We want to look at other added benefits. E.g., caniuse has better compat data, but we not the other info ... but I still want to be better than "MDN + caniuse data"; which even that isn't straightforward, because the level of detail doesn't match up ... jen, maybe if you could think, looking at the caniuse data, how would that be effectively integrated into a larger page, having all that information about current, older and future versions, but display that compactly ... similarly, another design challenge, is how to integrate the W3 tests; when you have 30 tests on a property, and a browser passes 25 of them, how do you display that information in a summary level, that someone could click on to drill down and discover the specific cases where it is or isn't supported. ...or, if you want to see how a feature is used, look at how the actual tests are written to see that. Do you want to think about that? jensimmons: On that issue, we could argue about what percentage of tests is required for support, but some tests are more important than others, and there's no way to program robots to be that smart. So I think what you're saying is good, don't try to convert to a binary supports/doesn't support, just display the number of tests passed, and click on it for the details, but the trick is to display that extended information in a useful way. ...but another thing, is to make sure that there is way for people to come along, if they do understand it, to translate it into a human explanation for others ...they could write "oh this is a little edge case, it's mostly supported", or "this is a major problem, don't use this feature yet" shepazu: A third, hybrid option, is to add the data to the page, but also work to categorize the tests as edge cases vs core features, and feed that information back to the test suite. ... I think that's what you were getting at, but the next step is to leave the data on the tests jensimmons: I think most people wouldn't really care about that. shepazu: the difference is, that once we've categorized things, then it can be updated automatically and affect how we display the information; people wouldn't have to read this, but it would affect what they'd see. ...somebody could take that data, and update it, for example if things that used to be edge cases are now being commonly used ...that would be a way of giving feedback to implementers, that this specific test is important to us now jensimmons: there are these sort of bleeding-edge technologies, like viewport units that you can mostly use, but you have to be careful, about where you can or can't use them, some are well supported (vh and vw), others are buggy (vmin, vmax) ...to have someone say, these things are important, they are supported, other things maybe it's not clear where they would be used, because they don't have the support to actually use them and discover the different ways they could be used shepazu: either way, we're talking about adding human annotation over the test results. If you can all think about how this could be better displayed or integrating, not just better than we're doing now, but better than everyone else, to display it more compactly, more accurately, I think that would be really useful. AmeliaBR: I think, what we want is to have the convenience, the level of detail about versions, that caniuse has, but have it at the much more detailed level as far as specific features shepazu: I think we have to do that, because that's how our site is laid out; we can't use it just as caniuse has it, because it doesn't fit in our site jensimmons: I can definitely start thinking about it AmeliaBR: long term, I'd really like to get to know the data on the W3 tests, and figure out how we can put a decent interface to that
Received on Tuesday, 16 September 2014 18:40:34 UTC