Move multi-paragraph descriptions out of the Try it section on HTML and WebAssembly pages - #45604
husamemadH wants to merge 8 commits into
Conversation
github-actions
Bot
added
Content:HTML
|
As I said before in #45563 (comment), these descriptions are too long to go before the "Try it" section. Ideally only the first paragraph, which is usually just a one-sentence overview, goes there. |
…le on HTML and WebAssembly pages
0251acb to
93b7f8a
Compare
|
Updated, only the first paragraph now moves above the demo. I also dropped 8 pages from this PR where the first paragraph ends in a colon and introduces a list that stays behind (tabindex, accesskey, data-*, call, and the four SIMD saturation pages) moving that sentence alone would separate it from its list. |
|
@wbamberg Not sure if the current change is what you had in mind but I think this is zero improvement. This content should live anywhere but in Try it. I think all this stuff should go into "Description". |
No it isn't. IMO the page should start with an (ideally) one-sentence description of the thing, e.g.
It should be followed by the demo, which gives people a quick idea of what the thing is (show, don't tell). Any more detailed stuff about the thing should go after the demo, in a top-level Description section. Sometimes, this might involve some rewording to make sure things stay coherent (e.g. if there's currently some way that the subsequent paragraphs depend on the first paragraph). That's what I meant when I said that this work needs to pay attention to semantics. Need to ask, does this still actually make sense as documentation, rather than a collection of blocks of "content" in some particular order. In fact, the HTML element page template suggests that the current organization is correct (i.e. that "more detail" should go after the demo, but not under its own heading. I think this is probably wrong and ought to be fixed. |
|
Oh yeah, that page template looks out of date. It doesn't even mention "Usage notes" which is basically HTML's equivalent of "Description". I'll manually fix up a few pages and you might let me know if it looks more like what you think. |
|
@wbamberg For simplicity I've simply done this:
The content may not be fully consistent or duplication-free this way, but I think it would be easier to review, and not much worse than before. |
Follow the pattern already used on address and datalist: keep the short overview and demo at the top, and put the extra paragraphs that were rendering inside Try it under Usage notes (or Description when that heading is the better fit).
|
Does this look like the right shape? |
Co-authored-by: wbamberg <will@bootbonnet.ca>
|
|
||
| ## Description | ||
|
|
||
| > [!NOTE] |
There was a problem hiding this comment.
this doesn't make sense as a description. Best to put it at the top, after the intro sentence.
| If the {{Glossary("user agent")}} can't play that, it moves on to the next option, whose `type` is specified as `video/mp4`. | ||
| If neither of those can be played, the text "This browser does not support the HTML video element." is presented. | ||
|
|
||
| {{InteractiveExample("HTML Demo: <source>", "tabbed-standard")}} |
There was a problem hiding this comment.
Oh man, why is there an interactive example in this guide.
There was a problem hiding this comment.
You keep discovering gems like this 😄
There was a problem hiding this comment.
😭 Let's deal with this in a follow-up.
wbamberg
left a comment
wbamberg
left a comment
There was a problem hiding this comment.
I think this is close.
Some of the <input> element pages already have H2 headings like ## Using the thing element which looks silly when combined with ## Usage notes, so we should just have one ## Usage notes including all the stuff. I already commented on this but it seems only some of them got fixed.
Also, some other pages already have de facto usage notes under their own H2 headings (e.g. the iframe page). It would be better to convert them to convert them to H3 and sit them under the new "Usage notes" H2. I think this is not a blocker though.
Again, this is the kind of thing I mean when I keep going on about paying attention to semantics.
Note, this is being done in #45614. If you get that merged you will get it for free, at least for that page. I personally think that moving this prose anywhere is an improvement of the status quo, where it is basically hanging without context. I don't think we necessarily have to fix everything about their page structure. |
github-actions
Bot
added
size/l
|
I think this is done ? |
|
This pull request has merge conflicts that must be resolved before it can be merged. |
This branch has not been deployed
4 participants
Description
The last of four PRs splitting up #45563. Draft, like #45603.
These are the 28 HTML, WebAssembly and media pages where more than one paragraph sits after the
{{InteractiveExample}}macro and therefore renders inside the "Try it" section. As currently written, each block moves up above the macro.The same open question as #45603 applies here — whether these belong above the demo or in a
## Descriptionsection after it. Whatever is decided there, I will apply the same treatment to this PR, so it is probably easiest to settle it on #45603 alone.The largest cases are in this PR:
<picture>and thetabindexglobal attribute both have eight paragraphs after the macro, which is well past the "very short summary" the template intends before the demo.Motivation
Same underlying issue as #45601: prose placed after the
{{InteractiveExample}}macro renders inside the "Try it" section, after the demo's code, instead of reading as part of the page's description.