Suggesting content improvements
2 minute read
If you notice an issue with the United Manufacturing Hub or one of its components, like the documentation, or have an idea for new content, then open an issue. All you need is a GitHub account and a web browser.
In most cases, new work on the United Manufacturing Hub begins with an issue in GitHub. UMH maintainers then review, categorize and tag issues as needed. Next, you or another member of the United Manufacturing Hub community open a pull request with changes to resolve the issue.
Opening an issue
If you want to suggest improvements to existing content or notice an error, then open an issue.
- Go to the GitHub repository for the content you want to improve, like the main repository or the documentation repository.
- Click Issues, then click New issue.
- There are multiple issue templates to choose from. Choose the one that best describes your issue.
- Fill out the issue template with as many details as you can. If you have a specific suggestion for how to resolve the issue, include it in the issue description.
- Click Submit new issue.
After submitting, check in on your issue occasionally or turn on GitHub notifications. Reviewers and other community members might ask questions before they can take action on your issue.
How to file great issues
Keep the following in mind when filing an issue:
- Provide a clear issue description. Describe what specifically is missing, out of date, wrong, or needs improvement.
- Explain the specific impact the issue has on users.
- Limit the scope of a given issue to a reasonable unit of work. For problems with a large scope, break them down into smaller issues. For example, “Fix the security docs” is too broad, but “Add details to the ‘Restricting network access’ topic” is specific enough to be actionable.
- Search the existing issues to see if there’s anything related or similar to the new issue.
- If the new issue relates to another issue or pull request, refer to it
either by its full URL or by the issue or pull request number prefixed
with a
#character. For example,Introduced by #987654. - Follow the Code of Conduct. Respect your fellow contributors. For example, “The docs are terrible” is not helpful or polite feedback.