Re: Removal of the Microformats examples

On 3 June 2015 at 03:00, James M Snell <jasnell@gmail.com> wrote:

> 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).
>

+1 to everything


>
> - James
>
>