About issues: "Issues can be created ..." / Broken ITS terminology

[Chealer]

Code of Conduct

• I have read and agree to the GitHub Docs project's Code of Conduct

What article on docs.github.com is affected?

https://docs.github.com/en/issues/tracking-your-work-with-issues/about-issues

What changes are you suggesting?

I suggest copy-editing the page.
The use case would be small projects which rely on GitHub to track their issues.
The expected outcome would be a page written in proper English.

Additional information

This is not a behavioral bug. But anyway, the basic issue I meant to report is conflation of issues with tickets (issue reports). Rather than issue reporting, the page refers to "issue creation". It also talks about "opening issues"(?) and "issue templates". This can be seen in the first 2 paragraphs:

You can create issues in your repository to plan, discuss, and track work. Issues are quick to create, flexible, and can be used in many ways. Issues can track bug reports, new features and ideas, and anything else you need to write down or discuss with your team. You can also break your work down further by adding sub-issues and easily browse the full hierarchy of work to be done.

Issues can be created in a variety of ways, so you can choose the most convenient method for your workflow. For example, you can create an issue from a repository, while adding sub-issues, convert a comment in an issue or pull request, create an issue from a specific line of code, or via a URL query. You can also create an issue from your platform of choice: through the web UI, GitHub Desktop, GitHub CLI, GraphQL and REST APIs, or GitHub Mobile. See Creating an issue.

And then, there is that "Creating an issue" page, which is filled with the same.

The following is not exhaustive, but just some hints:

Projects is strongly integrated with issues.

To stay updated on the most recent comments in an issue, you can subscribe to an issue to receive notifications about the latest comments.

To help contributors open meaningful issues that provide the information that you need, you can use issue forms and issue templates. See Using templates to encourage useful issues and pull requests.

You can @mention collaborators who have access to your repository in an issue to draw their attention to a comment.

For guidance on when to use an issue or a discussion, see Communicating on GitHub.

When a conversation in an issue is better suited for a discussion, you can convert the issue to a discussion.

License

This report (including all messages and attachments I add to it) is offered under the terms of CC0 1.0.

[welcome]

Thanks for opening this issue. A GitHub docs team member should be by to give feedback soon. In the meantime, please check out the contributing guidelines.

[Chealer]

This is not limited to documentation. In fact, just to report this, I had to click a "New issue" button (even though this goes back to at least 2021), which brought me to a puzzling "Create new issue" page, from which I managed to proceed to another "Create new issue" form. That confusing form, specifically designed to report behavioral bugs, starts with:

HUBBERS!! This is the github/docs open source repo. You may want to open an issue in the internal-only github/docs-content repo instead.

• Before you file an issue read the Contributing guide.
• Check to make sure someone hasn't already opened a similar issue.

This really needs to be reviewed by someone with user experience expertise.

[nguyenalex836]

@Chealer Thank you for raising this issue! I'll get this triaged for review ✨ Our team will provide feedback regarding the best next steps for this issue - thanks for your patience! 💛

[Mostafa-SAID7]

Thank you for your suggestion! Based on your feedback, it seems that the terminology on the page could be clarified to avoid confusion between "issues" and "issue reports."

[nguyenalex836]

@Chealer Thank you for taking the time to raise this issue! We appreciate your input, but given we review and improve our content according to users metrics, we'll be closing this issue at this time 💛

That confusing form, specifically designed to report behavioral bugs, starts with:

To clarify, this is a note intended for internal folks. Thank you again for sharing your feedback!

[Chealer]

@Chealer Thank you for taking the time to raise this issue! We appreciate your input, but given we review and improve our content according to users metrics, we'll be closing this issue at this time 💛

I don't really know what you mean by that, but you're welcome.

That confusing form, specifically designed to report behavioral bugs, starts with:

To clarify, this is a note intended for internal folks.

Thanks, part of it may indeed be, which is another thing to clarify.

Don't hesitate to ask if you need more information.

[Chealer]

How was this completed?

[Sharra-writes]

@Chealer This occurred before my time, but reading through, it appears other users were asked if they had difficulty understanding the page you identified, no one reported it as a problem, and so the team decided not to spend resources trying to fix it.

Many of our older "about" pages are admittedly a little clunky in their wording, but fixing them up to read better isn't currently a major priority. I occasionally dive in and clean one up when I can, so I can add this to my list.

[Chealer]

Greetings @Sharra-writes,

@Chealer This occurred before my time, but reading through, it appears other users were asked if they had difficulty understanding the page you identified, no one reported it as a problem, and so the team decided not to spend resources trying to fix it.

As I wrote, I couldn't really understand @nguyenalex836’s 2025-01-22 message, but if that’s what it meant, that was pretty cryptic.

And it doesn’t help at all in understanding the message I asked about ("nguyenalex836 closed this as completed on Jan 22").

Many of our older "about" pages are admittedly a little clunky in their wording, but fixing them up to read better isn't currently a major priority. I occasionally dive in and clean one up when I can, so I can add this to my list.

Thanks in advance. I just reviewed the page and whatever was done, it's clear from the very first sentence that that didn't fully fix.