Comments on Data on the Web Best Practices

Hi, Data on the Web Best Practitioners–

Thanks for publishing the Data on the Web Best Practices spec [1]. This 
will be useful for me, so I just finished reading it. Nicely done!

As discussed on Facebook, I have a few minor suggestions on the PR 
draft. :) I know this is late feedback, so please feel free to ignore it 
or push it to the next version. However, I would be considered any of 
these changes editorial, since none of them affect any conformance criteria.

I made a Github PR for each of these.

First, I noticed that two of the diagrams weren't accessible, so I made 
(mostly) accessible SVG versions of them. One of them (challenges.svg) 
originally used script to navigate in the main spec, and I replaced this 
with simple links to do the same thing (note: this technique needs the 
filename of the spec, which I assumed is "Overview.html", rather than 
"index.html"… change as needed). I adjusted the HTML file to use the 
preferred <object> element, rather than the <embed> element, to include 
these.

Newton has graciously already accepted this PR [2].

Second, I fixed a few minor typos and grammar problems [3]. These should 
be uncontroversial.

Third, I added short descriptive names to the namespaces table, with 
links to the bibliography (where present… you don't reference RDF). I 
think these short names would make it clearer and less intimidating to 
the new reader what those namespaces are for, but I understand if you 
don't consider that editorial at this stage. It's in the same PR as the 
typos, but you can easily roll it back.

Finally, I was really struck that the example data provider is named 
"John", rather than some gender-neutral name like "Adrian". While 
certainly unintentional, this risk perpetuating gender stereotyping in 
tech, and I think it's a good opportunity to use a gender-neutral name 
(and, for that matter, maybe one that isn't so obviously 
English-language). I'd be happy to make a PR for this, which would also 
affect some of the other dwbp-example files, and would need a couple of 
changes of pronoun from "he" to "they" (or to just avoid pronouns 
altogether). This would be a PC PR PR. :D

Again, I don't mind if you ignore or push these last comments off to a 
next version, but I thought I'd suggest them.


[1] https://www.w3.org/TR/2016/PR-dwbp-20161215/
[2] https://github.com/w3c/dwbp/pull/504
[3] https://github.com/w3c/dwbp/pull/505

Thanks!
Doug

Received on Tuesday, 10 January 2017 10:47:32 UTC