docs: fix typos, add missing words, correct case, improve code samples, &c. #7114

j9t · 2021-09-24T17:02:06Z

Fixed typos (“more complication situations”)
Added missing words (“…as”, “the”)
Corrected case (“subject line”)
Expanded abbreviations to aid understanding (“processing instructions”)
Made code samples consistent
Closed example code
Removed “obviously” to aid tone and helpfulness
Added space between key modifiers (for clarity)

(As chapter 4 is pretty large I’m submitting this PR now to continue with more edits for this chapter in a separate branch and PR.)

/grouping-content.html ( diff )
/interaction.html ( diff )
/sections.html ( diff )
/semantics.html ( diff )
/text-level-semantics.html ( diff )

* Corrected case (“subject line”) * Added missing words (“…as”) * Expanded abbreviations to aid understanding (“processing instructions”) * Made code samples consistent * Added space between key modifiers (for clarity) Signed-off-by: Jens Oliver Meiert <jens@meiert.com>

* Fixed typos (“more complication situations”, missing article) * Closed example code * Removed “obviously” to aid tone and helpfulness Signed-off-by: Jens Oliver Meiert <jens@meiert.com>

source

annevk · 2021-09-27T13:00:10Z

source

@@ -18648,7 +18649,8 @@ interface <dfn interface>HTMLQuoteElement</dfn> : <span>HTMLElement</span> {
 &lt;blockquote cite="https://quotes.example.org/s/sonnet130.html">
  &lt;p>My mistress' eyes are nothing like the sun,&lt;br>
  Coral is far more red, than her lips red,&lt;br>
-  ...</code></pre>
+  ...&lt;/p>
+&lt;/blockquote></code></pre>


I think I'd prefer leaving this as-is, although I could see using … instead. Note that this happens further down as well in <p>We shall now discuss these points... and you did not change it there. And I think it might end up being confusing if changed there and perhaps it's here as well.

I missed the other place. Would it work for you if we change it there, too? As blockquote has no optional end tag I believe this sets a better example.

I think the problem is that it ends up being unclear whether the elided text is part of the example or not.

With this reverted I'd be okay with merging this.

I don’t feel this makes the example itself less clear, but if this is something we want to rule out, how about shortening the example then?

<p>His next piece was the aptly named <cite>Sonnet 130</cite>:</p> <blockquote cite="https://quotes.example.org/s/sonnet130.html">…</blockquote>

This would be well-formed and valid and make the example more concise.

I prefer the current setup. If you feel strongly we could wait for @domenic to make a decision.

I thought about this and I believe here’s the problem, here’s what rubs me: We truncate these examples like it was prose. What I think makes the examples better in a technical doc is not truncating like it was prose, but truncating like it was code.

We can still truncate the prose in the code, but by making a distinction between copy and code we can make the examples more clear, by not omitting possibly important technical detail. In this case, as mentioned originally, not inadvertently suggesting that </blockquote> was optional.

(I just updated the other example (“He began his list of "lessons"…”), too, though I’d file the problem there under consistency, not under problematic truncating.)

Unless @domenic feels otherwise I continue to think we should leave this unchanged.

Signed-off-by: Jens Oliver Meiert <jens@meiert.com>

j9t · 2021-09-27T17:44:40Z

Thanks @annevk. Took care of further edits or responded.

Signed-off-by: Jens Oliver Meiert <jens@meiert.com>

j9t · 2022-01-10T15:45:32Z

@annevk, @domenic, is there someone to complete the review of this PR?

annevk

Apart from three bits this looks okay to me. Perhaps you can split those out into a separate PR.

annevk · 2022-01-12T15:42:38Z

source

  <p class="XXX">It is expected that counterparts to the above rules also apply to
-  <code>&lt;?xml-stylesheet?></code> PIs and HTTP `<code data-x="http-link">Link</code>` headers.
-  However, this has not yet been thoroughly investigated.</p>
+  <code>&lt;?xml-stylesheet?></code> processing instructions and HTTP `<code
+  data-x="http-link">Link</code>` headers. However, this has not yet been
+  thoroughly investigated.</p>


I hadn't noticed this before, but since this is a XXX we should leave it unchanged. This is aimed at people who know what PI means.

annevk · 2022-01-12T15:43:15Z

source

@@ -18648,7 +18649,8 @@ interface <dfn interface>HTMLQuoteElement</dfn> : <span>HTMLElement</span> {
 &lt;blockquote cite="https://quotes.example.org/s/sonnet130.html">
  &lt;p>My mistress' eyes are nothing like the sun,&lt;br>
  Coral is far more red, than her lips red,&lt;br>
-  ...</code></pre>
+  ...&lt;/p>
+&lt;/blockquote></code></pre>


Unless @domenic feels otherwise I continue to think we should leave this unchanged.

annevk · 2022-01-12T15:43:23Z

source

@@ -18711,7 +18713,7 @@ be conceded to have merits.&lt;/blockquote>
 &lt;blockquote>Finally, one should be prepared for the threat
 of breakdown in negotiations at any given moment and not
 be cowed by the possibility.&lt;/blockquote>
-&lt;p>We shall now discuss these points...</code></pre>
+&lt;p>We shall now discuss these points...&lt;/p></code></pre>


I don't think we should change this either.

j9t · 2022-01-12T17:04:59Z

Thanks @annevk!

As mentioned in October, I don’t have the bandwidth anymore to work on this. Feel free to cherry-pick from this and other open PRs and issues.

A personal note, I didn’t feel that proactive contributions were welcome (not targeted at you, quite the contrary—an unemotional observation). I understand that proactiveness is also a risk, that the work may for good and bad reasons not be considered. However, if contributor work is left without comment for months, risking that work to be for naught and yet indirectly setting the expectation that contributors need to be on stand-by for an indefinite period of time, it seems to show little respect and appreciation for the work that contributors put in. (I know that from a Google perspective, we typically try to avoid such an experience.)

Maybe this feedback can be considered at any time there’s attention on improving the contributor experience.

annevk

That's totally fair, but unfortunately we don't have the resources of Google. At the end of the day it's just a couple of people that need to balance many conflicting priorities.

Kaleidea · 2022-01-13T16:26:54Z

I didn’t feel that proactive contributions were welcome (not targeted at you, quite the contrary—an unemotional observation).
[...] it seems to show little respect and appreciation for the work that contributors put in.

@j9t I concur with your observation and go a bit further. The background: I've spent a few weeks drafting a specification and even implementing it in browsers, yet my work was ignored and rejected in hurtful ways. What I've experienced was not a resource issue as I've done the editors' job and more, but instead, I see a cultural issue of lack of openness and appreciation. That is contrary to the WHATWG principles and I wonder how this could be improved.

j9t added 2 commits September 24, 2021 13:02

docs: incorporate spec review notes

af26cb6

* Fixed typos (“more complication situations”, missing article) * Closed example code * Removed “obviously” to aid tone and helpfulness Signed-off-by: Jens Oliver Meiert <jens@meiert.com>

annevk reviewed Sep 27, 2021

View reviewed changes

docs: incorporate review feedback

20ddda3

Signed-off-by: Jens Oliver Meiert <jens@meiert.com>

docs: make key combo handling consistent (spaces around “+”)

a275326

Signed-off-by: Jens Oliver Meiert <jens@meiert.com>

j9t mentioned this pull request Sep 30, 2021

docs: small fixes and improvements #7128

Merged

annevk reviewed Jan 12, 2022

View reviewed changes

undo

e405911

annevk approved these changes Jan 13, 2022

View reviewed changes

annevk merged commit 0909fda into whatwg:main Jan 13, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: fix typos, add missing words, correct case, improve code samples, &c. #7114

docs: fix typos, add missing words, correct case, improve code samples, &c. #7114

j9t commented Sep 24, 2021 •

edited by pr-preview bot

Loading

annevk Sep 27, 2021

j9t Sep 27, 2021

annevk Sep 28, 2021

annevk Sep 29, 2021

j9t Sep 29, 2021

annevk Sep 29, 2021

j9t Sep 29, 2021 •

edited

Loading

annevk Jan 12, 2022

j9t commented Sep 27, 2021

j9t commented Jan 10, 2022

annevk left a comment

annevk Jan 12, 2022

annevk Jan 12, 2022

annevk Jan 12, 2022

j9t commented Jan 12, 2022

annevk left a comment

Kaleidea commented Jan 13, 2022

docs: fix typos, add missing words, correct case, improve code samples, &c. #7114

docs: fix typos, add missing words, correct case, improve code samples, &c. #7114

Conversation

j9t commented Sep 24, 2021 • edited by pr-preview bot Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

j9t Sep 29, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

j9t commented Sep 27, 2021

j9t commented Jan 10, 2022

annevk left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

j9t commented Jan 12, 2022

annevk left a comment

Choose a reason for hiding this comment

Kaleidea commented Jan 13, 2022

j9t commented Sep 24, 2021 •

edited by pr-preview bot

Loading

j9t Sep 29, 2021 •

edited

Loading