Skip to content

Update project documentation structure and clarity#2318

Open
dagood wants to merge 2 commits into
microsoft/mainfrom
dev/dagood/docs
Open

Update project documentation structure and clarity#2318
dagood wants to merge 2 commits into
microsoft/mainfrom
dev/dagood/docs

Conversation

@dagood
Copy link
Copy Markdown
Member

@dagood dagood commented May 27, 2026

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.gz and zip)" 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.

Copilot AI review requested due to automatic review settings May 27, 2026 23:23
@dagood dagood requested a review from a team as a code owner May 27, 2026 23:23
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.md pointing Microsoft-internal readers back to the README’s support resources.
  • Restructures eng/doc/README.md with clearer headings and a more complete, descriptive index of eng/doc documentation.

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.

Comment thread README.md Outdated
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants