indieweb / indieweb/jf2

Various small phrasing notes

Open
#32 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Waiting for Commenter
Dominant language
HTML
Stars
12
Forks
4
PR merge metrics
No merged PRs in 30d

Description

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

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing the Use Cases, consumers, Section 5.1, and Section 7 text identified in the issue. Check each phrase for ambiguity, then revise or clarify the wording and definitions so the sections communicate their intended meaning consistently.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.