Removal of the Microformats examples

I am sorry to have had to miss the WG call this morning. (actually,
I'm not, my daughter was getting an award for academic achievement and
there was no way I was going to miss the awards ceremony). In any
case, after reviewing the IRC log from the call, I thought it
worthwhile to make a comment on the removal of the Microformats
examples.

For the record, with my editor's hat on, I'm strongly -1 on adding the
Microformats examples back into the document. In fact, I'd like to go
a step further and strip out the Microdata and RDFa examples as well,
leaving only the JSON-LD and Turtle.

I've posted a detailed note on github
(https://github.com/jasnell/w3c-socialwg-activitystreams/issues/83#issuecomment-108145255)
and have included the contents of the note below (note: the snippet
below was written in response to Tantek's comment here:
https://github.com/jasnell/w3c-socialwg-activitystreams/issues/83#issuecomment-106661247)

---
Given that a well defined mapping between the two is not likely to
exist, it makes no sense to bundle the examples together in the core
or vocabulary document. Producing a separate Note that shows a
non-normative transformation between the JSON-LD syntax and
Microformats would be far easier to create and maintain over time.
Especially given, as you [tantek] say, "This is not just a difference
in syntax".

You [tantek] claim that the "The point of providing the microformats
examples is to show clearly how much simpler they are". Given that I
am the one who initially added those examples, I can say with quite a
bit of authority that that was not the point. The point of providing
the microformats examples was to demonstrate a clear one-to-one
mapping of the vocabulary model across alternative syntaxes, primarily
to show that the vocabulary was not limited to strictly JSON-LD --
even tho JSON-LD was the only normative syntax being defined.

As it currently stands, there are hundreds of examples within the two
documents, each with five different variants of differing levels of
complexity. I do not have the time available to devote to ensuring
that every one of those variants is correct, nor do I currently have
the time to define the mapping between the JSON-LD model and the
Microformats model. Given that (a) most of the microformats examples
were incorrect (b) there's been only a single pull request in six
months correcting only some of the microformats examples and (c) the
Microformats syntax is not a normative requirement in the spec, I made
the editorial decision to remove that particular set of examples.

I believe it would be further worthwhile to also remove the Microdata
and RDFa examples as well, primarily for the purpose of simplifying
the specification documents overall.

What I would strongly encourage is for those members of the WG who
have an interest in the Microformats syntax to produce a draft Note
that details the mapping of the AS2 vocabulary to the Microformats
model, with correct examples. I do not have the time to help edit such
a draft Note.

If someone wishes to take the time to submit a PR against the current
drafts adding corrected Microformats examples back into the document,
then I will merge it in. At this point in time, however, I do not have
the free time to work on producing hundreds of non-normative examples
that, in my opinion, add nothing but unnecessary complexity back into
the document.
---

Simply reverting the commit that removed the examples is not possible
because there have been other changes made to the document since.
Plus, simply reverting the commit does not address the problem that
(a) most of the microformats examples were incorrect (b) there is no
"correct" mapping we can use to make them correct (c) no one seems to
have the time to submit PR's to help correct them (I've received
exactly one in the past six months) and (d) the Microformats examples
were strictly non-normative. My goal right now is to get the AS2 core
and vocabulary documents finished and ready for candidate release
status. Having broken, non-normative examples in the spec does not
help me as the editor make that happen.

So, I would simply reiterate: A draft Note that outlines the mapping
between Microformats and AS2 would be far more valuable than adding
the existing set of broken examples back into the core and vocabulary
documents (even if not all the examples were broken).

- James

Received on Wednesday, 3 June 2015 01:01:32 UTC