Re: [csswg-drafts] CSSWG specs need usable test suite docs

The Working Group just discussed `CSSWG specs need usable test suite docs`.

<details><summary>The full IRC log of that discussion</summary>
&lt;dael_> Topic: CSSWG specs need usable test suite docs<br>
&lt;dael_> github: https://github.com/w3c/csswg-drafts/issues/2438<br>
&lt;rego> so we keep duplicating files all over the place, or use absolute paths :(<br>
&lt;dael_> fantasai: I 100% agree testing documentation sucks.<br>
&lt;dael_> tantek: Problem highlighted is our testing documentation makes it very hard for community of people helping us to grow.<br>
&lt;dael_> florian: Shouldn't we delete what's in the wiki and point to WPT's documentation and if that's insufficient file issues on that.<br>
&lt;dael_> gsnedders: The build system and test harness should be there.<br>
&lt;dael_> fantasai: And meta<br>
&lt;dael_> florian: Meta is on WPT.<br>
&lt;dael_> florian: I'd like to rpopose we delete our test documentation and any time we need to reference instructions we point to WPT and then we file issues if there's a bug.<br>
&lt;dael_> tantek: Their tests are completely opaque. I disagree. Here's a bunch of things that look identical and if you guess right after 3 levels you'll find information.<br>
&lt;dael_> florian: The wiki is old information, though.<br>
&lt;dael_> tantek: First thing I did is go through the wiki and it has rudementary information on how to do it. If you want to help witht he problem look at stuff.<br>
&lt;dael_> florian: I added a bunch of documentation to WPT.org for stuff we had.<br>
&lt;dael_> tantek: WPT is opaque.<br>
&lt;dael_> florian: The information is mostly complete, discoverability is horrendous.<br>
&lt;fantasai> s/bunch of things/bunch of links/<br>
&lt;dael_> gsnedders: My objection to putting everything on css wiki...WPT documentation is bad and the solution here isn't to write new docuemtnation, it's to fix it.<br>
&lt;dael_> florian: It's not bad for containing information.<br>
&lt;dael_> gsnedders: It's hard to nav and not at the level for browser vendors or new people. Too verbose for borwser vendors.<br>
&lt;dael_> TabAtkins: florian do you remember how often browser vendors look at old WD instead of what's in TR? They'll look at wrong things.<br>
&lt;dael_> gsnedders: And again it doesn't start basic enough level.<br>
&lt;dael_> tantek: You start at the spec, it links to the test suite, you try a test and it fails. Look at test and it fails. now you want to fix it. Now you're in trouble.<br>
&lt;dael_> tantek: If we fix that on csswg wiki that's a huge improvement. We're not going to move all documentation here. But we want an avg web dev to have a prayer.<br>
&lt;dael_> gsnedders: Some of the problem may be test harness links to sheppard for bugs. Where should we file bug on the test harness?<br>
&lt;dael_> [silence]<br>
&lt;dael_> tantek: First scenario is make it easy to report bugs on test. Second thing we hsould make easy is for people to contribute tests. Both of those can be incrementally fixed without fixing everything.<br>
&lt;dael_> fantasai: I've sent prob 7 people a list of links to Moz documentation from 2001 which was very straight forward. That'st he documentation we need. It's clear these are the people they need help.<br>
&lt;dael_> tantek: Can you link to those in this issue?<br>
&lt;dael_> fantasai: Yeah.<br>
&lt;dael_> tantek: We won't solve it here but I'm hoping we can align on objectives.<br>
&lt;dael_> florian: Rephasing my position, I don't mean delete everything from the wiki. Do not attempt to duplicate what's in WPT in the wiki. Additional guidance to help people find the things or help people know what to do.<br>
&lt;dael_> tantek: Agree with the caveat that undiscoverable or unlinkable is the eq. to not there.<br>
&lt;dael_> florian: Yeah.<br>
&lt;dael_> florian: WPT.org needs a search button too. That would be useful.<br>
&lt;dael_> astearns: File an issue for that?<br>
&lt;dael_> florian: Yes.<br>
&lt;dael_> florian: WPT.org is done with Jeckal, right?<br>
&lt;dael_> gsnedders: Yes.<br>
&lt;gsnedders> s/Jeckal/Jekyll/<br>
&lt;dael_> florian: There are plug ins for search.<br>
&lt;dael_> [talking about how to add search]<br>
&lt;dael_> astearns: Anything more?<br>
</details>


-- 
GitHub Notification of comment by css-meeting-bot
Please view or discuss this issue at https://github.com/w3c/csswg-drafts/issues/2438#issuecomment-380854919 using your GitHub account

Received on Thursday, 12 April 2018 15:54:54 UTC