Defining page types

[wbamberg]

Tracking issue for openwebdocs/project#91.

In this project we will aim to:

• define a complete set of page types for all of MDN's pages
• document the types in our meta-docs
• add a front matter items to every page representing its type

The main aim of this is to define types for structured pages - that is, for pages that are always expected to conform to a particular organization. However, I think it will be helpful to have an explicit "guide" type for pages that aren't structured pages.

Scope

In the first part I'd like to understand the scope of this project. The output of this will be a collection of "doc sets" which we will analyze.

A doc set is a group of related pages on MDN - like the JS docs, or the Learn area, and so on.

I'm doing this in a spreadsheet, here: https://docs.google.com/spreadsheets/d/14RX8EEKPpeYkP2cF5Y_ZKF3JpNJ_24OL7stvZWNJLIY/ .

In the "all doc sets" tab I've listed:

• all top-level directories under MDN
• all top-level directories under Web

Each of these, more or less, is a doc set.

I've then asked whether each doc set contains structured content. Doc sets that don't contain structured content are out of scope - they're all "guide" pages.

Then for each doc set that contains structured content I've assigned a priority 1-3. I think for now we should consider the P1 sets, which are:

• API
• CSS
• HTML
• HTTP
• JavaScript
• Learn

The pages in those doc sets are the pages that we will look at for this project.

I think we should execute the project in two phases:

• defining the page types we want to have
• adding the page types to the pages

I think we should do all of the analysis first: that is, we should define page types for all doc sets before we update any pages. That's because it is likely that we will end up changing our mind about some definitions as we analyze later doc sets.

Page type definition

So for the first phase we'll define page types for the following doc sets:

• API: [page types] Define page types for Web/API #16255
• CSS: [page types] Define page types for CSS #15540
• HTML: [page types] Define page types for HTML #22705
• HTTP: [page types] Define page types for HTTP #22761
• JavaScript: [page types] Define page types for JavaScript #16156
• Learn

Page type implementation

For the second phase we'll add the defined values to the pages.

[teoli2003]

Noting this here so I don't forget it:

I noticed you added dictionary as a page type for API. If generally we are getting rid of pages describing dictionaries, we will likely keep some of them. I have been calling them (in my mind only!) interfaces without methods and we are avoiding the term dictionary as they are implemented as JS objects.

I think we don't need a separate page type for them and reuse the interface page type.

[wbamberg]

Noting this here so I don't forget it:

I noticed you added dictionary as a page type for API. If generally we are getting rid of pages describing dictionaries, we will likely keep some of them. I have been calling them (in my mind only!) interfaces without methods and we are avoiding the term dictionary as they are implemented as JS objects.

I think we don't need a separate page type for them and reuse the interface page type.

Yes, I agree that we will keep some "dictionaries". I'm happy to call them "interfaces without methods". We'll need to find a balance between:

• too many types: the more types, the more complicated the thing is
• too few types: which makes it harder for us to distinguish things.

For example if we put dictionaries in the "interface" type, then when we lint, we have to make the "Methods" section in interfaces optional (or let it be empty). That means we have weaker guarantees for interfaces. This might be fine of course, but it's a thing to keep in mind.

[teoli2003]

There are anyway interfaces without methods: ImageData (spec).

Up to now, I have not understood why some are interfaces (without methods) and others dictionaries… (I may be missing something!)

[Elchi3]

I guess it is because ImageData wants to be a constructible object (it has two constructor forms).
Dictionaries are usually ordered maps that just store settings and can't do anything else, like you don't have constructors with them, I believe.

Generally, the WebIDL spec https://webidl.spec.whatwg.org might be good to consult when defining page types for APIs.

[wbamberg]

Defined page types

In this comment I'll list all the defined page types as we agree on them. Eventually this list should make its way into some meta-documentation.

Generic types

guide
landing-page

Web/API

web-api-overview
web-api-global-function
web-api-global-property
web-api-interface
web-api-constructor
web-api-instance-method
web-api-instance-property
web-api-static-method
web-api-static-property
web-api-event
webgl-extension
webgl-extension-method

[Elchi3]

webgl-extension
webgl-extension-method

Is there a discussion somewhere why these aren't folded into web-api-interface and web-api-instance-method?

[teoli2003]

Yes, there.