w3c / w3c/string-meta

section on document-level @language and @dir has confusing examples

Open
#23 2 comments 0 reactions 1 assignee View on GitHub

@aphillips is already working on this.

Since Feb 4, 2019.

Dominant language
HTML
Stars
16
Forks
10
PR merge metrics
No merged PRs in 30d

Description

There are some issues with the examples in the section on document level @language and @dir that make it a bit confusing.

First, the example begins with a link whose text is "original example" but the link is broken; I think it should instead link to section 1.3.1.

Then it's worth noting that this section has three chunks of JSON, but it doesn't clearly identify which of them represent good practice and which of them represent bad practice.

There are a number of differences between the examples that seem to confuse things unnecessarily:

  • the second example not only removes the default, but also (as it says) introduces overriding to fix places where that default was incorrect and the language and direction metadata in the first example were thus incorrect
  • the third example reintroduces the default but uses the opposite default from the first example
  • the third example also introduces an entirely separate concept that it doesn't even mention, by having the "title" be a multi-language array (or object? It's using incorrect syntax that's a blend of array and object syntax) that offers the title in multiple languages.
  • the third example has an incorrect language on the publisher

It seems to me that:

  • multiple parallel examples would probably be clearer if they showed the same semantics in different ways, rather than differing semantically
  • it's probably worth introducing the concept of objects that offer an option in multiple languages (perhaps both with arrays and objects), but that may well be the most complex topic here and it probably shouldn't be slipped in in the third part of an example without being mentioned; I think it probably deserves its own subsection with distinct examples

(I got here from w3ctag/design-reviews#178.)

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.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.