Clarify required and optional prose sections for HTML elements #55

wbamberg · 2019-06-12T22:36:09Z

The recipe for HTML elements lists the following as mandatory sections:

Short description
Usage notes
See also

and the following as optional sections:

Overview
Attributes text (this is for elements that want to add some extra prose for the attributes list)
Accessibility concerns

...with of course the option of providing any extra sections that are specific to a particular element. This doesn't quite match up with the existing stumptown content (as scraped from MDN).

It also doesn't quite match up with the specification @chrisdavidmills wrote for HTML docs: https://docs.google.com/document/d/17R-jyS2WVQ9_OIfErRZWRdPSAVYYauF3wfkJUeG07PI/edit#heading=h.nlsh2gn0fxac:

Summary/intro text

OK, call that "Short description".

Additional usage information; a full explanation of how to use the element.

Call that "Overview".

Styling with CSS

We don't have this at all.

Accessibility concerns and best practices

We have this as "Accessibility concerns".

See also

We have this of course.

So: the doc adds "Styling with CSS", which seems like a useful section at least sometimes, and also omits "Usage notes", which seems like a good omission (we would be better to fold that content into "Overview"). So suggest we could change the recipe to:

Mandatory sections:

Short description
See also

Optional sections:

Overview
Styling with CSS
Attributes text
Accessibility concerns

I don't know if we should be more prescriptive than this, and perhaps make "Overview" or even "Styling with CSS" mandatory.

For "Overview": there are existing elements which don't have an overview, so if we make it mandatory we have to update them. For some elements we might want to move the Usage notes to Overview (e.g. https://developer.mozilla.org/en-US/docs/Web/HTML/Element/i#Usage_notes).

For "Styling with CSS" there will of course be some elements where it's not applicable at all, and others where there's nothing very interesting to say. So this probably should be kept optional.

@chrisdavidmills , thoughts?

Acceptance criteria

Recipe for HTML elements is complete
Existing content that would not comply with the recipe has been identified
Issues have been opened for updating content, updating build-json, adding linting, and updating the renderer

Tasks

(see #55 (comment) for details):

update the recipe
identify existing content that would not comply with the recipe
open issue(s) for updating content, updating build-json, adding linting, and updating the renderer

chrisdavidmills · 2019-06-13T09:32:24Z

@wbamberg this all sounds good to me.

On the subject of overview, yes, I was intending that usage notes basically gets folded into overview where it appears.

I was intending to start getting HTML pages updated to the new structure over the course of Q3, and we could start with the 50 particular pages that you are working on for stumptown. It just depends on whether end of Q3 will be quick enough for your purposes. So. ideally overview should be mandatory, but maybe keep it optional for now if this is going to be a blocker for you?

wbamberg · 2019-06-13T17:26:15Z

So. ideally overview should be mandatory, but maybe keep it optional for now if this is going to be a blocker for you?

I think we should define the format we think is correct, and flag pages that fail so we know which ones to fix. So let's go with:

Mandatory sections:

Short description
Overview
See also

Optional sections:

Styling with CSS
Attributes text
Accessibility concerns

If it turns out that there are legitimate reasons to omit "Overview" we'll need to think again.

(there's also talk of structuring "See also", since it's basically just a list of links - and that would enable us to render it in other contexts etc. I guess we should talk about that in yet another issue...)

chrisdavidmills · 2019-06-13T17:59:35Z

OK, that works for me — your logic is sound, and I agree with the structure.

ddbeck · 2019-07-11T10:08:07Z

Following a discussion with Will, I'm going to take on updating the recipe for these new requirements and finding out what existing stumptown content fails to meet them. I think those two things alone will satisfy this issue, though as Will explained, concluding this consequently kicks off some new tasks such as:

implementing linting to enforce the recipe
updating the actual Wiki pages to reflect that structure, as far as possible
updating the corresponding content in stumptown (maybe using a scraper!)
updating the build-json code to reflect the recipe (e.g. remove usage notes as a named section, and in other ways make it line up)
updating the renderer to reflect the recipe

Given that, I think these are the tasks needed to satisfy this specific issue ("Clarify required and optional prose sections")

update the recipe (Update required and optional sections in HTML recipe #74)
identify existing content that would not comply with the recipe
open issue(s) for updating content, updating build-json, adding linting, and updating the renderer

peterbe · 2019-07-11T17:48:38Z

... and updating the renderer

Happy to help on that one. Arguably, when we do we'll make it a separate issue.

ddbeck · 2019-07-26T11:33:20Z

I wrote a script to find the content which would not comply with the new recipe. Here's what I found. Once #74 is merged, I'll open issues to address the classes of problems here (e.g., we should probably handle missing see-also content separately from missing overviews).

content/html/reference/elements/abbr
  Missing sections: [ 'overview' ]
  Contains deprecated sections: [ 'usage_notes' ]
content/html/reference/elements/address
  Contains deprecated sections: [ 'usage_notes' ]
content/html/reference/elements/article
  Contains deprecated sections: [ 'usage_notes' ]
content/html/reference/elements/aside
  Missing sections: [ 'overview' ]
  Contains deprecated sections: [ 'usage_notes' ]
content/html/reference/elements/audio
  Contains deprecated sections: [ 'usage_notes' ]
content/html/reference/elements/b
  Contains deprecated sections: [ 'usage_notes' ]
content/html/reference/elements/base
  Missing sections: [ 'see_also' ]
  Contains deprecated sections: [ 'usage_notes' ]
content/html/reference/elements/blockquote
  Missing sections: [ 'overview' ]
  Contains deprecated sections: [ 'usage_notes' ]
content/html/reference/elements/body
  Missing sections: [ 'overview' ]
content/html/reference/elements/br
  Contains deprecated sections: [ 'usage_notes' ]
content/html/reference/elements/button
  Contains deprecated sections: [ 'usage_notes' ]
content/html/reference/elements/canvas
  Missing sections: [ 'overview' ]
  Contains deprecated sections: [ 'usage_notes' ]
content/html/reference/elements/caption
  Missing sections: [ 'overview' ]
  Contains deprecated sections: [ 'usage_notes' ]
content/html/reference/elements/cite
  Missing sections: [ 'overview' ]
  Contains deprecated sections: [ 'usage_notes' ]
content/html/reference/elements/code
  Missing sections: [ 'overview' ]
  Contains deprecated sections: [ 'usage_notes' ]
content/html/reference/elements/data
  Missing sections: [ 'overview' ]
content/html/reference/elements/datalist
  Missing sections: [ 'overview' ]
content/html/reference/elements/dd
  Missing sections: [ 'overview' ]
content/html/reference/elements/del
  Missing sections: [ 'overview' ]
content/html/reference/elements/dfn
  Missing sections: [ 'overview' ]
  Contains deprecated sections: [ 'usage_notes' ]
content/html/reference/elements/dialog
  Missing sections: [ 'overview' ]
  Contains deprecated sections: [ 'usage_notes' ]
content/html/reference/elements/div
  Contains deprecated sections: [ 'usage_notes' ]
content/html/reference/elements/dl
  Missing sections: [ 'overview' ]
  Contains deprecated sections: [ 'usage_notes' ]
content/html/reference/elements/em
  Missing sections: [ 'overview' ]
  Contains deprecated sections: [ 'usage_notes' ]
content/html/reference/elements/embed
  Contains deprecated sections: [ 'usage_notes' ]
content/html/reference/elements/figcaption
  Missing sections: [ 'overview' ]
content/html/reference/elements/figure
  Missing sections: [ 'overview' ]
  Contains deprecated sections: [ 'usage_notes' ]
content/html/reference/elements/footer
  Missing sections: [ 'overview' ]
  Contains deprecated sections: [ 'usage_notes' ]
content/html/reference/elements/h1-h6
  Missing sections: [ 'overview' ]
  Contains deprecated sections: [ 'usage_notes' ]
content/html/reference/elements/head
  Missing sections: [ 'overview' ]
  Contains deprecated sections: [ 'usage_notes' ]
content/html/reference/elements/header
  Missing sections: [ 'overview' ]
  Contains deprecated sections: [ 'usage_notes' ]
content/html/reference/elements/html
  Missing sections: [ 'overview' ]
content/html/reference/elements/i
  Missing sections: [ 'overview' ]
  Contains deprecated sections: [ 'usage_notes' ]
content/html/reference/elements/iframe
  Missing sections: [ 'see_also' ]
content/html/reference/elements/kbd
  Contains deprecated sections: [ 'usage_notes' ]
content/html/reference/elements/label
  Contains deprecated sections: [ 'usage_notes' ]
content/html/reference/elements/legend
  Missing sections: [ 'overview' ]
content/html/reference/elements/li
  Missing sections: [ 'overview' ]
content/html/reference/elements/table
  Missing sections: [ 'overview' ]
content/html/reference/elements/video
  Contains deprecated sections: [ 'usage_notes' ]

peterbe · 2019-07-26T12:58:02Z

I would love to review an extension to our .Travis.yml that turns that into errors.

ddbeck · 2019-07-29T12:48:30Z

Yep! I'll open a PR for my script after the recipe changes land. 👍

ddbeck · 2019-07-30T15:55:51Z

OK, I've opened #89, #90, and mdn/yari#65. I've satisfied the acceptance criteria and closing this.

wbamberg mentioned this issue Jun 12, 2019

Render all HTML elements currently included in stumptown mdn/sprints#1712

Closed

ddbeck mentioned this issue Jul 10, 2019

Structure "see also" content #66

Open

ddbeck self-assigned this Jul 11, 2019

jmswisher added this to the MC Lyte (S1 Q3 2019) milestone Jul 12, 2019

ddbeck mentioned this issue Jul 23, 2019

Update required and optional sections in HTML recipe #74

Merged

This was referenced Jul 30, 2019

Fix HTML content to match new recipe #89

Open

Write linter to validate that pages follow their recipes #90

Closed

Update renderer for new HTML reference recipe mdn/yari#65

Closed

ddbeck closed this as completed Jul 30, 2019

joedarc mentioned this issue Aug 4, 2019

References #89 - Fix HTML content to match new recipe #95

Merged

ddbeck mentioned this issue Oct 14, 2019

Add initial linter #169

Merged

wbamberg mentioned this issue Oct 30, 2019

HTML global attributes #211

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Clarify required and optional prose sections for HTML elements #55

Clarify required and optional prose sections for HTML elements #55

wbamberg commented Jun 12, 2019 •

edited by ddbeck

chrisdavidmills commented Jun 13, 2019

wbamberg commented Jun 13, 2019

chrisdavidmills commented Jun 13, 2019

ddbeck commented Jul 11, 2019 •

edited

peterbe commented Jul 11, 2019

ddbeck commented Jul 26, 2019

peterbe commented Jul 26, 2019

ddbeck commented Jul 29, 2019

ddbeck commented Jul 30, 2019

Clarify required and optional prose sections for HTML elements #55

Clarify required and optional prose sections for HTML elements #55

Comments

wbamberg commented Jun 12, 2019 • edited by ddbeck

Acceptance criteria

Tasks

chrisdavidmills commented Jun 13, 2019

wbamberg commented Jun 13, 2019

chrisdavidmills commented Jun 13, 2019

ddbeck commented Jul 11, 2019 • edited

peterbe commented Jul 11, 2019

ddbeck commented Jul 26, 2019

peterbe commented Jul 26, 2019

ddbeck commented Jul 29, 2019

ddbeck commented Jul 30, 2019

wbamberg commented Jun 12, 2019 •

edited by ddbeck

ddbeck commented Jul 11, 2019 •

edited