-
Notifications
You must be signed in to change notification settings - Fork 19
Stumptown update: June 2020
The overall goal we are working towards is: lint and fix up key Open Web docs content, including JS, CSS, HTML, HTTP, and WebAPI P1 docs.
We're currently working on finishing the JS docs (~900 pages). Next up is CSS (~1000 pages), and after that WebAPIs (~1100 pages).
The main goal of this sprint was to finish implementing the linter for the JS docs and fix the resulting linter errors. A subsidiary goal was to define structures for the CSS docs, so we could get started linting them.
Daniel landed the last part of the work to lint the order in which page elements (ingredients) appear in the page. This generated a lot of errors!
We are agonizingly close to 0 errors for the JavaScript docs as I write this. Work here included:
- writing a lot of examples for pages that were missing them
- adding missing specifications to
SpecData.json - reorganizing pages to make them follow a consistent order
- reworking our
Proxydocumentation so it makes more sense
All this means we can make some assertions about our JavaScript documentation. For example:
-
Every reference page:
- has an "Examples" section
- has a compat table
- if it has an interactive example, has it in the correct place and with the correct markup
- uses a consistent ordering for H2 headings
- either has a link to a specification taken from
SpecData.json, or explicitly and consistently notes that it is nonstandard.
-
Every page documenting a JavaScript class:
- uses a consistent structure to list methods and properties
- has a link to its constructor, unless it explicitly exempts itself
- lists methods and properties alphabetically.
We've found and fixed many errors to get to this point. And now we can track these assertions, so we know when, for example, new pages are added that break them. When our docs live in GitHub we should be able to run the linter in CI, so we fail the builds if PRs break our assertions.
This was slower than we expected, mostly because the JS cleanup work ended up taking longer than we expected. But we did land recipes for CSS properties and CSS shorthand properties. The most interesting thing here is probably that CSS shorthand properties include an ingredient that explicitly lists all the properties that the shorthand contains, so we will now be able to present this in a consistent way.
Our main goal for this sprint is to finish updating the linter for our CSS docs. This means:
- deciding which page structures we want to require for CSS
- updating the linter to check our CSS docs against these structures
We'd also like to make good progress fixing CSS linter errors, although we don't expect to finish in this sprint.
We'd also like to make good progress writing recipes for the WebAPI docs, so we can get started updating the linter in the sprint after this.