search

indieweb / jf2

JF2 Editors Draft
http://jf2.spec.indieweb.org/
11 stars 3 forks source link

Various small phrasing notes #32

Open strugee opened 7 years ago

strugee commented 7 years ago

The Use Cases section is a bit confusing:

JF2 has evolved as a result of a variety of use-cases for different implementations exploring ways to simplify their existing use of canonical parsed microformats2 JSON output. All of these use cases in particular are simply to have a single format for the storage and use of social web objects.

seems to say that JF2 comes from a variety of use-cases but then says that all these use-cases are the same?

Also, "validate" in "Various services...validate proper semantics" is kinda confusing to me - validate in terms of what? Proper mf2 semantics? This is particularly confusing to me since validators are a thing; I don't know if this is a human doing the validating or a machine. Maybe just say "inspect mf2 semantics"?

The list of examples in the "consumers" section includes "a feed reader" and "a feed aggregator" but I'm not really sure what the difference between these is; perhaps they should be combined?

Section 5.1 is called "Reserved Keywords" but "keywords" seems like kind of a funky way to describe this. Maybe just "reserved properties"? Not sure. And not really a big deal tbh.

The content-type reserved keyword is defined as "the MIME type of the containing object" but this is a little confusing. Is this supposed to mean, the MIME type of the authoritative representation the JF2 document was derived from?

Section 7. Collections says posts can "live" inside collections - this is kind of a weird verb to use.

Stopping there as I gotta do some other stuff before the morning :)

dissolve commented 6 years ago

I think many of these have been dealt with, but when you have a chance, can you review and create new issues for any you feel need further discussion