Make JS description sections optional

[Elchi3]

Makes "Description" sections optional throughout JS docs. When linting the whole JS tree:

Before:

Missing from javascript-method: prose.description                             143 errors     javascript-method/prose.description    
Missing from javascript-constructor: prose.description                        63 errors      javascript-constructor/prose.description   
Missing from javascript-property: prose.description                           22 errors      javascript-property/prose.description                                  
Missing from javascript-language-feature: prose.description                   19 errors      javascript-language-feature/prose.description                          
74 message types (9737 messages, ✖ 800 errors, ⚠ 8937 warnings) in 919 files

After:

70 message types (9490 messages, ✖ 553 errors, ⚠ 8937 warnings) in 919 files

I believe we should make description sections optional. Of course, this raises the question to authors when to have a "Description" section and when not. Currently, I believe, it is there when the method or any language feature needs more explanations that doesn't fit into the short description. Not all pages need these longer texts, though. Sometimes what's in "Description" could probably be put into (multiple) examples, but sometimes it is really just text and not code. So, my feeling is that the "Description" section is a bit like a guide page as a section in the reference. The author can freely make use of it to go deeper and explain concepts etc. More thoughts on this welcome.

Follows up on the comment I made here #348 (comment)

[wbamberg]

I agree that lots of pages omitting a thing is a strong signal that it should be optional.

One question though is: in the recipes for CSS properties and for HTML elements we have mandatory "Overview" sections, that are supposed to follow the interactive example, if there is one. These sections are supposed to have special-case handling that omits the H2 (as for "short_description"). This is supposed to accommodate some text in between the interactive example and the named sections like "Attributes" (see for example https://developer.mozilla.org/en-US/docs/Web/HTML/Element/address).

What's the difference between "Overview" and "Description" ? They seem to fulfill basically the same function.

I think my suggestion would be:

• let's use "Description" everywhere, and make it optional
• let's make it a normal section with an H2. Then only "short_description" is special-case, and I'm more comfortable with that.

[Elchi3]

What's the difference between "Overview" and "Description" ? They seem to fulfill basically the same function.

Thanks for thinking outside of JS docs! I agree "overview" fulfills basically the same function.

I think my suggestion would be:
let's use "Description" everywhere, and make it optional
let's make it a normal section with an H2. Then only "short_description" is special-case, and I'm more comfortable with that.

I like this plan. To fully implement it, would there be follow-ups, or is any more work to be done in this PR?

[wbamberg]

To fully implement it, would there be follow-ups, or is any more work to be done in this PR?

Why not, in this PR, update all the recipes that have prose.overview to have instead prose.description?? That gives us a consistent base.

[Elchi3]

Why not, in this PR, update all the recipes that have prose.overview to have instead prose.description?? That gives us a consistent base.

Done that now, for some reason I thought this would be more complex but looks like it isn't. I hope it is reviewable.

Some unrelated stuff seem to have made it into the commit. Wasn't there when I reviewed the diff. I guess it is this magic?

husky > pre-commit (node v12.16.1)
🔍 Finding changed files since git revision 75204b2.
🎯 Found 8 changed files.
✍️ Fixing up project-docs/html-element.md.
✍️ Fixing up project-docs/stumptown-status.md.
✍️ Fixing up project-docs/stumptown-writers-guide.md.
✅ Everything is awesome!

[ddbeck]

Some unrelated stuff seem to have made it into the commit. Wasn't there when I reviewed the diff. I guess it is this magic?

This is because the husky pre-commit command applies prettier in ways that the package scripts prettier commands don't—in this case, it's running on all files, including Markdown. I'm not sure when that got added or why, but that's what's doing it.

[wbamberg]

At least, I don't think these formatting changes break anything, and it would be good to have the substantive change in the recipes.