feature and issue templates: change warning formatting

[maxim-belkin]

• Have you followed the guidelines in our Contributing document?
• Have you checked to ensure there aren't other open Pull Requests for the same change?
• Have you added an explanation of what your changes do and why you'd like us to include them?
• Have you written new tests for your changes? Here's an example.
• Have you successfully run brew style with your changes locally?
• Have you successfully run brew tests with your changes locally?

---

This PR changes long titles to short titles + description. Spin-off from #8017

• Feature template: link
• Issue template: link

[Rylan12]

LGTM

One minor bikeshed (if that's the appropriate term 🤔) that shouldn't stop a merge

[MikeMcQuaid]

I'm not sure I see the advantage of having these on two lines instead of one?

[MikeMcQuaid]

This seems fine 👍🏻

[MikeMcQuaid]

This PR changes long titles to short titles + description.

Can you explain "why" rather than "what"? What problem for maintainers or contributors have you observed that will be fixed by this change?

[maxim-belkin]

Can you explain "why" rather than "what"? What problem for maintainers or contributors have you observed that will be fixed by this change?

I can only speak about my motivation to make this suggestion. I believe that titles should be clear and succinct, such as "X" or "Do X". Such titles provide good anchor points in people's brains. Titles that include instructions (such as "include command output") or are complete sentences (such as "How the feature would be relevant ...") are less effective because they're convoluted with "secondary" words: the word "relevant" in the second example above appears in the sixth place and the whole point of that paragraph is "relevance" to 90% of Homebrew users. All the additional information and instructions can be provided elsewhere -- in a subtitle, comment, or a paragraph with futher instructions.

The benefit to maintainers is that they'll be able to say things like "In X section you say...". In general, short titles seem to be more visually appealing to me than the long ones.

[MikeMcQuaid]

In general, short titles seem to be more visually appealing to me than the long ones.

On the flip side, splitting them from "long title" to "short title and description" makes cut content longer (vertically) which increases the feel of having more text to read and, the more text there is to read, the less likely people are to read any of it.

[maxim-belkin]

Comparison

1. Current feature template
2. Current feature template + H1->bold text change
3. This PR
   

Long titles + H1 headings actually make things appear to be longer. We can do the H1 -> H2 switch in feature template only but my point about the wordiness of titles remains -- I think shorter titles make it look more "professional".

[MikeMcQuaid]

Given the lack of 👍🏻s from other maintainers here and the stalling: maybe close it if that's OK?

[maxim-belkin]

Given the lack of 👍🏻s from other maintainers here and the stalling: maybe close it if that's OK?

@Homebrew/brew, could you guys please vote for (👍) or against (👎) this?

@MikeMcQuaid, if maintainers decide against this, I can open a separate PR for the change that you OK-ed.

[SeekingMeaning]

On the flip side, splitting them from "long title" to "short title and description" makes cut content longer (vertically) which increases the feel of having more text to read and, the more text there is to read, the less likely people are to read any of it.

I agree with this

[reitermarkus]

I think as long as the “long” titles fit into one line they are short enough.

[maxim-belkin]

I think as long as the “long” titles fit into one line they are short enough.

That's what I want too: currently 3 out of 4 titles span 2 lines (and the first "Please note..." title shouldn't be really a title).

[reitermarkus]

currently 3 out of 4 titles span 2 lines

Where? These all fit in 1 line for me when rendered.

[reitermarkus]

Ok, not quite all. The only one which doesn't fit (apart from the “Please note …”) is the “How the feature would be relevant …” title.

[Rylan12]

I, personally, like these changes. I feel more strongly about changing the "please note" text from H1 to bold. To me (as a maintainer), this text is just a distraction and there's no need to have it take up so much space and I find that it takes away from the rest of the content which is more important. The bold is a good compromise because it still clearly stands out from the rest of the text, and I'm not sure it's any less effective than H1. Remember that all text appears the same size and with the same emphasis in the Write tab when creating an issue. It's only when you switch to the Preview tab that you see the formatting. For me, this only happens at the end so I'm just as likely to read the text if it's a heading or bold.

I also like the other changes, but I don't feel as strongly about it and won't be upset if they aren't accepted. I think it looks much cleaner to have short and descriptive titles. This makes it much easier to glance at the section heading and immediately know what the contents are. I haven't memorized the order of the template, so I still need to read each heading, and it's much easier for me to read the one-word title and know immediately what that section is about than to have to read a whole sentence.

The way I see it, there are two sides to this. One is that we want to be clear about exactly what information we need and what we expect to contributors who are opening the issue. Is "The motivation for the feature" really any better than just having the word "Motivation"? Same with "Description". I'm not sure that having the entire sentence is any more descriptive (except maybe in the "Relevance" section). If anything, I would think that people are more likely to read smaller blocks of text than the entire sentence anyway. The bottom line is that people either read and follow it or they don't. I don't think that having full sentences makes people choose to follow the template when they otherwise wouldn't.

The second side is from the maintainer side. The maintainers should be able to easily read the issue using the template to get whatever information they need. There's no need for me to have to focus on a huge message warning about deleting the template. Same with the headings: I know what information I need, so to just have a single word heading makes it much easier. I can figure out which section I'm looking at much more quickly from the word "Relevance" than from the sentence "How the feature would be relevant to 90% of Homebrew users".

Anyway, sorry for the long comment. This is just my opinion but I have much less experience than many of the other maintainers so I may be in the minority.

[MikeMcQuaid]

The bold is a good compromise because it still clearly stands out from the rest of the text, and I'm not sure it's any less effective than H1.

Fine with me.

Is "The motivation for the feature" really any better than just having the word "Motivation"? Same with "Description". I'm not sure that having the entire sentence is any more descriptive (except maybe in the "Relevance" section). If anything, I would think that people are more likely to read smaller blocks of text than the entire sentence anyway. The bottom line is that people either read and follow it or they don't. I don't think that having full sentences makes people choose to follow the template when they otherwise wouldn't.

Completely agree with this. I think adding more text that communicates essentially the same information across multiple lines makes it worse.

[MikeMcQuaid]

Can this PR be scoped down to just be these changes above (and same on feature suggestion)? If so: 👍🏻 to merge.

[MikeMcQuaid]

Perfect, thanks @maxim-belkin and sorry for all the bike shedding 😬