About discussions edits

[Sharra-writes]

Why:

Trying to improve the scannability of About discussions.

What's being changed (if available, include any code snippets, screenshots, or gifs):

If the goal of an "about" is to present the reader with reasons to use a product, it doesn't make sense to fill the article with all the intricate details of how the product works. I cut a lot of that, trying to give more of an overview.

Check off the following:

• A subject matter expert (SME) has reviewed the technical accuracy of the content in this PR. In most cases, the author can be the SME. Open source contributions may require an SME review from GitHub staff.
• The changes in this PR meet the docs fundamentals that are required for all content.
• All CI checks are passing and the changes look good in the review environment.

[github-actions]

How to review these changes 👓

Thank you for your contribution. To review these changes, choose one of the following options:

• Spin up a codespace
• Set up a local development environment

A Hubber will need to deploy your changes internally to review.

Table of review links

Note: Please update the URL for your staging server or codespace.

The table shows the files in the content directory that were changed in this pull request. This helps you review your changes on a staging server. Changes to the data directory are not included in this table.

Source	Review	Production	What Changed
discussions/collaborating-with-your-community-using-discussions/about-discussions.md	fpt ghec ghes@ 3.17 3.16 3.15 3.14 3.13	fpt ghec ghes@ 3.17 3.16 3.15 3.14 3.13
discussions/managing-discussions-for-your-community/managing-discussions.md	fpt ghec ghes@ 3.17 3.16 3.15 3.14 3.13	fpt ghec ghes@ 3.17 3.16 3.15 3.14 3.13

Key: fpt: Free, Pro, Team; ghec: GitHub Enterprise Cloud; ghes: GitHub Enterprise Server

🤖 This comment is automatically generated.

[lecoursen]

Overall, this PR does a really great job of reorienting the article around "why" instead of "how." Since you asked for a 30% review, I mostly only left some ideas to consider, with a few line-level suggestions purely to function as examples. Let me know if you have any questions! ✨

[lecoursen]

You haven't made any updates to the "Further reading" section, but just wanted to mention that our approach to links has increasingly been to limit them to only those that are critical to the main purpose of the article. As you identified in the OP, the goal is something like "understand what Discussions is and why I should use it," and I'd argue that none of the articles in "Further reading" are closely enough related to that goal to be included. I'd consider removing the whole section and instead adding a "Next steps" section where we send folks to the one article that makes the most sense... in this case, probably the most logical destination after deciding that Discussions is right for you would be the quickstart, so you can start using it.

[lecoursen]

I'd consider updating the intro above as well, to better summarize the purpose of the article. I like an intro to answer the question "What will I gain by reading this article?", providing the information a user needs to determine whether they should open the article, rather than serving as a TLDR of the content. In this case, something like "Learn how discussions can help you communicate with your community."

[lecoursen]

I think these last two list items may not belong. Correct me if I'm wrong, but to me this is intended to be a list of real-list tasks you can accomplish using Discussions (share information, get community input, answer questions, etc). These last two items feel more like qualities of Discussions that help you accomplish all the tasks in the list, but are not tasks themselves. I'd remove the "Upvote discussions..." item entirely (I feel like that's just a given for this type of functionality, nothing to brag about), and we could move the "Foster an inviting atmosphere..." to the paragraph above. Something like this:

With {% data variables.product.prodname_discussions %}, the community for your project can create and participate in conversations within a repository or organization. Maintainers, contributors, and visitors can gather in a central location with an inviting atmosphere, without third-party tools.

[Sharra-writes]

You're right. I don't feel confident right now deciding the finer details of what should and shouldn't be included, so I think I erred on the side of including things that were in the article. Happy to cut more, though. 👍

[lecoursen]

I think details about exactly who can create discussions and when are outside the scope of this article as they're more "how to use Discussions" than "why." But I do think it could make sense to convey the general concepts that (a) Discussions can be enabled/disabled by maintainers and (b) when enabled, anyone who can see a repo/org can create and participate in a discussion there. I think we can probably just rephrase the paragraph to accomplish that in a more conceptual way... something along these lines:

Suggested change

	Anyone who can has access to a repository can create and participate in discussions once a repository administrator or project maintainer has enabled {% data variables.product.prodname_discussions %}. Similarly, if an organization owner enables {% data variables.product.prodname_discussions %} for an organization, anyone who can view the source repository can create an organization discussion.
	Anyone who can access a repository or organization can create and participate in discussions there. However, an administrators must enable {% data variables.product.prodname_discussions %} for the repository or organization first.

[lecoursen]

I think we can remove both of these links, or at least the second one.

[lecoursen]

Small point, but both this list and the one below are full sentences and the items should therefore each end in a period. 😄

[lecoursen]

I question whether organization is an important enough topic for an entire section, at least for the goal of helping folks understand the value of Discussions and whether they should use it. I think it's likely that a single sentence or paragraph about how you can organize discussions using categories and labels is enough for this article. Could we include that in the "Managing discussions" section?