search

openwebdocs / project

project documentation, policies & meeting minutes
http://openwebdocs.org
Creative Commons Zero v1.0 Universal
359 stars 42 forks source link

OWD project: page types #91

Closed wbamberg closed 1 year ago

wbamberg commented 2 years ago

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: https://github.com/mdn/content/issues/3424#issuecomment-845271047.

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:

In practice we would do this in sections - JS, CSS, Web/API, and so on.

See also

Prioritization criteria

Effort

Large? Need to:

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

ddbeck commented 2 years ago

One little suggestion I wanted to make: a page type identifier proposal ought to speak to versioning (spitballing here, but javascript-class:1, etc.). Then when a page spec inevitably changes, the affected pages can be explicitly upgraded, rather than broken and fixed.

Elchi3 commented 2 years ago

@wbamberg can you give an update (high-level is enough) on where we are with page types right now?

wbamberg commented 2 years ago

@Elchi3 , this is done for Web/API (page types defined, documented, and applied) and in progress for CSS and JavaScript.

Elchi3 commented 2 years ago

Thanks Will! I found the tracking bugs. Adding them here, too.

teoli2003 commented 2 years ago

I think we should add "MathML" (should be close to HTML) and maybe "SVG" there (like close to HTML too, but the whole area is in a bad state)

Elchi3 commented 2 years ago

In the planning call yesterday, we decided:

Assigning @wbamberg to do the above prep work.

wbamberg commented 2 years ago
  • Have a separate project/task to change the apiref macro to use page types instead of tags. (and possible other things, with the idea being that page types should be used by something, so that they don't become unmaintained.)

-> https://github.com/mdn/yari/pull/7223

wbamberg commented 1 year ago

Update!

The following areas still need page types, and will probably need us to define new types:

The following areas still need page types, but we can just use the generic guide and landing-page types:

Also, to call this project done, we want linting to be in place:

teoli2003 commented 1 year ago

Once the last PRs referenced above have landed, we will still need a last check before calling this project done.

In files/en-us/, the following command should return 0 results: grep -rL "^page-type:" --include="index.md".