Update project documentation structure and clarity#2318
Open
dagood wants to merge 2 commits into
Open
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
Updates repository documentation to make support/contact channels easier to discover and to separate product support guidance from the Go release-support policy, improving readability for both internal and external readers.
Changes:
- Refocuses
README.md“Support” section on support channels and moves Go version support details into a distinct “Release cycle and policy” section. - Adds a cross-link in
SUPPORT.mdpointing Microsoft-internal readers back to the README’s support resources. - Restructures
eng/doc/README.mdwith clearer headings and a more complete, descriptive index ofeng/docdocumentation.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| SUPPORT.md | Adds a TIP callout linking to README support resources (Microsoft-internal channels discoverability). |
| README.md | Reorganizes support vs release policy content; clarifies release announcement channels; adds “tar.gz and zip” note for binary archive link. |
| eng/doc/README.md | Rewrites the doc index with clearer structure, maintained-branch notice, and more descriptive link names. |
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
A few people tried to contact us recently and didn't all find the channels they were expecting. (If anyone sees this: issues are great! Pinging individual developers internally is also fine, but causes delayed responses.) With that in mind, took another look at these docs.
The main change is to focus the "Support" section on product support and move "what versions of Go do you support" to its own distinct section. I expect that some people see how the Support section starts and ignore the rest because it's the wrong kind of support.
Including a hint about what support details people will find on the internal page may entice users to go there. Sometimes eng.ms doesn't load cleanly (for me) and without knowing what I'm going to find there, I might not browse it. (This might also be a useful hint for anyone asking Copilot to find these details.)
Leave SUPPORT.md to be specific to GitHub, but include a link back to the readme to make the internal support channels more discoverable.
Add a "(
tar.gzandzip)" note to the "Binary archive" link. That list has gotten busier, and sometimes I don't remember that name for what I'm looking for, and these terms stand out more. (Not all that related to the other changes, just a personal nitpick.)Improve
eng/doc/README.md: simplify the links by using descriptive names from headers, fill out the list, and tidy up.