OWD project: page types #91
Description
What is a page type?
A page type is a concise, human-readable term that identifies the type of web platform feature that an MDN page is about. For example, it might identify that a particular page documents a CSS property, or a JS method, or an HTML element.
Why page types are important
It's important for reference docs to be consistent, so they contain the same kind of information, organized in the same kind of way. For example, it's important that every CSS property page includes a browser compatibility table and that it appears in the same spot on every page, under the same title. Different types of page should include different elements: for example, a JS class page should have a link to the page describing its constructor, and a CSS shorthand property should contain a list of the properties it sets.
To be able to make rules like this, we need the concept of page types. And of course we use this concept all the time: whenever we say something like "this page ought to have a Syntax section" we are implicitly leaning on page types.
Also, any time want to present a collection of docs in an organized and navigable way - as in the sidebar for a JS global object, for example, where we want to have separate lists for properties, static methods, and instance methods - we're leaning on the concept of page types.
So we already have page types. What we are missing is a sharp and consistent way to define them.
How we represent page types at the moment
On MDN we currently use a few different hints to represent the type of thing a page documents, but the most common one is the page tag. The main problem with using tags for this is that they don't have any semantics. So if we define a tag like "CSS property" it's not at all obvious why this should not apply to, say, a landing page listing all CSS properties (and in fact this kind of blurring of the meaning of tags happens all the time). It would be a lot clearer to have a dedicated front matter key for this with its own definition. See also: mdn/content#3424 (comment).
We also describe page type templates in the MDN contribution docs: https://developer.mozilla.org/en-US/docs/MDN/Structures/Page_types. But these are incomplete and don't correspond to any identifier in the page - so they don't offer a way to map from a template to a particular page.
What a page type could look like
In this proposal the page type is a new front matter key called "page-type" whose value is a single string. Its possible values could be something like:
javascript-class
javascript-constructor
javascript-method
javascript-property
css-at-rule
css-data-type
css-function
css-property
...and so on
What we would use page types for
Sidebars
At the moment MDN pages call a macro to create the sidebar. So CSS pages include {{CSSRef}} at the top, for example. If pages instead of a page-type, and that can determine the sidebar to use, we don't need authors to make these macro calls any more: the correct sidebar can automatically be chosen by Yari.
Note that this won't work for all cases. In particular guide pages and landing pages don't map to a sidebar (because there can be JS, guides, or CSS guides, ...), so even if we do want to define "guide" and "landing-page" types (which is not certain) they would not be enough to determine the sidebar. However, this is a small minority of cases (probably less than 10%).
Tags
As noted above, we use tags as page types for building sidebars. We could replace all these references with references to page types instead.
Linting against a specification
More interestingly, given a reliable way to identify the page type, we could define a specification for pages of given type. The specification could list the set of elements that a page of that type must or may to contain. We can then test our pages against that specification, and know that our pages are consistent (or, where they are not). For example, we could have a list of pages that don't have a BCD table, but should.
Building pages to a specification
With linting, people write pages and we use the specification to check that they have a valid structure. The inverse of that is where people provide components of documentation, and a specification for a page, and the system builds complete pages. This is better than linting in some ways because authors don't have to understand the structure and don't have the chance to get it wrong.
We already do this to some extent using things like BCD, mdn/data, and interactive examples as components of a page, but we could take it a lot further. Why do authors have to remember the position on the page where the BCD table or the interactive example live?
We might start by linting pages, then eventually move towards building pages. Or we might build parts of pages, and lint the rest, and gradually build more and more pieces.
What's the actual project?
The current proposal is:
- define a complete set of page types for MDN's reference pages
- document the types in our meta-docs
- add a front matter items to every reference page representing its type
In practice we would do this in sections - JS, CSS, Web/API, and so on.
See also
Prioritization criteria
Effort
Large? Need to:
- define page types for all reference pages
- add them to all the pages
In practice the initial project might target a subset of the docs.
Dependencies
None.
Community enablement
Eventually, this would make it easier to contribute docs successfully, by making it clearer what's needed in a page.
Momentum
n/a
Enabling learners
More reliable docs benefit all users.
Enabling professionals
More reliable docs benefit all users.
Underrepresented topics / ethical web
n/a
Operational necessities
n/a
Addressing needs of the Web industry
n/a