Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve spec readability #646

Open
11 tasks
jyasskin opened this issue Jun 20, 2023 · 0 comments
Open
11 tasks

Improve spec readability #646

jyasskin opened this issue Jun 20, 2023 · 0 comments
Labels
spec Relates to the spec

Comments

@jyasskin
Copy link
Member

jyasskin commented Jun 20, 2023

The specification is hard to read, I think because it's almost entirely algorithms and definitions, without enough non-normative text and diagrams to give readers the context for how each algorithm is meant to fit in.

  • Add new sections that group the algorithms in meaningful ways.
  • Give most algorithms a short introductory paragraph saying what they're meant to do and what exactly they return in each case
    • When it is not clear, having a first-step assertion in algorithms that assert whether the steps are running on the main thread or in parallel would be great
  • Add some diagrams showing the lifecycle of an interest group, and any other system-wide information that would be best presented in diagrams.
  • Add "domintro" blocks under each IDL block telling developers what the function arguments and interface and dictionary fields mean.
  • It'll probably be easier to read browserSignals in https://wicg.github.io/turtledove/#report-result if it were initialized with a <dl> instead of the long list of "Set foo["bar"] to baz".
  • It would be helpful to have a <dfn> for the generateBid(), scoreAd(), etc functions that users are supposed to define, so that all the uses could cross-link to eachother.
  • In section 9, https://wicg.github.io/turtledove/#structures, we could benefit from introductory paragraphs saying what each structure is for. Because some of them are primarily used (I think?) to pass to JS functions inside the Script Evaluation section, those should probably become WebIDL dictionaries that can easily convert to JS objects.
  • What's a "joining site"?
  • Privacy section: The first sentence is a little fluffy and could probably be removed. You could say that Protected Audience ensures that at most N bits can flow from one origin to another for each T time or V visits to the site?
  • Privacy section: "The browser can enforce that" should come with a link to how the browser does that enforcement. Just an anchor link to part of the spec would be a good improvement here.
  • "Leading bid info" should be an actual infra struct. Right now it's just a bag of definitions
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
spec Relates to the spec
Projects
None yet
Development

No branches or pull requests

2 participants