project icon indicating copy to clipboard operation
project copied to clipboard
verified publisher icon openwebdocs

OWD project: page types

Open wbamberg opened this issue 3 years ago • 7 comments

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:

  • 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

  • https://github.com/mdn/content/discussions/5162

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

wbamberg avatar Mar 22 '22 23:03 wbamberg

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.

ddbeck avatar Mar 23 '22 11:03 ddbeck

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

Elchi3 avatar Sep 05 '22 14:09 Elchi3

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

wbamberg avatar Sep 09 '22 00:09 wbamberg

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

  • [x] API: https://github.com/mdn/content/issues/16255
  • [x] CSS: https://github.com/mdn/content/issues/15540
  • [x] HTML
  • [x] HTTP
  • [x] JavaScript: https://github.com/mdn/content/issues/16156
  • [x] Learn

Elchi3 avatar Sep 09 '22 08:09 Elchi3

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)

teoli2003 avatar Sep 09 '22 09:09 teoli2003

In the planning call yesterday, we decided:

  • To split this up into smaller projects (possibly per content area)
  • Have a separate project/task to validate page types
  • 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.)

Assigning @wbamberg to do the above prep work.

Elchi3 avatar Sep 15 '22 11:09 Elchi3

  • 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 avatar Sep 23 '22 23:09 wbamberg

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:

  • [x] Lint YAML/front-matter header

wbamberg avatar Mar 08 '23 21:03 wbamberg

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".

teoli2003 avatar Jul 06 '23 06:07 teoli2003