How are our pages structured?

MDN
#1

Hi All,

One of our next goals for improving the article pages is to try to communicate their structure better to our visitors. To do this I need to give The Brigade a clear idea of what our page structure is.

So… what’s our page structure? Do we have a common structure we use for references? Is it the same or different between CSS/HTML/JS/APIs/Extentions? Do we have a common structure we use for tutorials and guides?

I think many of you are experts in certain areas, you should chime in with what you know and I’ll make sure it gets to Brigade in a coherent format.

Thanks,
Stephanie.

#2

Sorry to rush you, but I need this info by 8:00AM Pacific Time.

Thanks,
Stephanie.

#3

Er, 8:00AM Pacific on Thursday >_<

#4

The Page Types meta-doc page lists the various page types, and links to exemplars, but it doesn’t try to describe the structures.

@sheppy was working on creating templates for standard reference pages, and may be able to shed more light.

#5

So, we have a pretty standard structure that we strongly encourage but don’t always enforce right now. Sometimes we need to fudge it a little when an API is quirky in some way. And of course much of our older content hasn’t been updated to use the new structures, which I would love for us to have time to attend to but we haven’t as yet.

If you need skeleton versions of pages, I can get those together for you (I need to do them anyway). I don’t know if that’s what you’re after though.

Sheppy

#6

CSS property pages

I think we should be aiming for a structure like this:

  • (overview - no H2): interactive example and overview text
  • H2. Syntax: definitive explanation of the syntax
    • H3. Values
    • H3. Formal syntax
  • H2. Examples: any more complex/sophisticated examples
  • H2. Specifications: table with links to specifications
  • H2. Browser compat: browser compat table

Example: https://developer.mozilla.org/en-US/docs/Web/CSS/box-sizing

Not all pages exactly follow this structure, but most are close to it. One major difference is that just about all the existing pages have a “See also” H2, and I’d like us to consider using some alternative nav for this kind of thing.

#7

Browser extensions:

JS function pages

Should probably aim for:

  • (overview - no H2)
  • H2. Syntax
    • H3. Parameters
    • H3. Return value
  • H2. Examples
  • H2. Browser compat

Example: https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/tabs/executeScript

Note that “Specifications” is missing compared to the CSS pages. Perhaps it should be included, and link to https://browserext.github.io/browserext/.

Note also that all the actual pages have “Examples” and “Browser compat” the wrong way round. I need to take the time to fix this.

JS event pages

Should probably aim for:

  • (overview - no H2)
  • H2. Syntax
    • H3. Listener arguments
  • H2. Examples
  • H2. Browser compat

Example: https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/tabs/onActivated

Note that they’re not terribly close to this at the moment.

JS type pages

Should probably aim for:

  • (overview - no H2)
  • H2. Syntax
  • H2. Browser compat

Example: https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/tabs/MutedInfo

Note that these pages currently uses “Type” instead of “Syntax”, but they should probably use “Syntax”.

Manifest key pages

Should probably aim for:

  • (overview - no H2)
  • H2. Syntax
  • H2. Examples
  • H2. Browser compat

Example: https://developer.mozilla.org/en-US/Add-ons/WebExtensions/manifest.json/author

Note that this is currently missing the “Syntax” H2, but it should probably have one.

1 Like
#8

[WIP] I’m working on this gist to provide info about the structures used across the HTML/CSS and JavaScript sections (Reference).
Some of it is already redundant with what @wbamberg added and parts are yet to be filled.

#9

There is also the property table for CSS pages. Is the suggestion that we remove that? If not, I’d at least move it to the bottom of the page and collapse it by default.

#10

The gist contains what I’ve been able to collect for HTML/CSS/JavaScript reference before the deadline.

This is a bit rushed/drafty but provides info regarding the structure for different categories of pages.
By no means this is supposed to be a “normative” document, many pages will be a bit different from the “common” structure I tried to get. This gist would actually be more helpful to create new pages respecting those templates rather than wanting to update every page which would “just be a bit different”.

@fscholz : /I’ll complete with the other “classes” of pages for JS later on./ Done
@sheppy : I hope you can find this useful for the overall meta-structure-documentation
@wbamberg : some verification on CSS would be welcome :slight_smile:

2 Likes
#11

This is really great. Thanks Sphinx!

1 Like
#12

We don’t want to get rid of it, since for SEO purposes having those property links there is helpful.

Sheppy

#13

Maybe we are talking about different things, Sheppy? I meant the box with things like “canonical order”, etc. Not sure about SEO value of that.

#14

Ah, yeah, I thought you meant something else. I think that information needs to be there but should move to be near the bottom of the page.

Sheppy