Add table of contents to documentation directory #26743
Conversation
docs/README.md
Outdated
| | [Working with EventSources and EventCounters](EventSourceAndCounters.md) | Guidance on adding event tracing to a library | Contributors needing to add event tracing for diagnostics purposes | | ||
| | [Tests on Helix](Helix.md) | An overview of the Helix test environment | Contributors debugging tests in Helix or looking to understand the output from Helix builds | | ||
| | [Issue management](IssueManagementPolicies.md) | Overview of policies in place to manage issues | Community members and collaborators looking to understand how we handle closed issue, issues that need author feedback, etc | | ||
| | [Package archives](PackageArchives.md) | | | |
There was a problem hiding this comment.
This document and the entry for it should be removed from the 'master' branch. It's not relevant in our newer branches.
docs/README.md
Outdated
| | [How references are resolved](ReferenceResolution.md) | Overview of dependency reference setup in the repo | Contributors looking to understand how package references are configured in the repo | | ||
| | [Servicing changes](Servicing.md) | Documentation on how to submit servicing PRs to previous releases | Collaborators to submit patches or backports to prior releases, contains the "Shiproom Template" | | ||
| | [Shared framework](SharedFramework.md) | Overview of the ASP.NET Core Shared framework | Contributors looking to understand the policies in place for managing the code of the shared framework | | ||
| | Submodules | | | |
There was a problem hiding this comment.
Left this empty because I don't think we need docs on submodules here. We don't use them aggressively and this time of stuff is better suited for the official Git docs.
There was a problem hiding this comment.
Curious why a non link instead of just no mention?
There was a problem hiding this comment.
My plan was to either document it or delete the file and the link altogether if folks felt it wasn't necessary. So kept it in here for now to start the discussion. I'm in favor of deleting the file...
There was a problem hiding this comment.
Seems fine to leave if we already have a doc written for it, it doesn't hurt does it?
There was a problem hiding this comment.
I know I've definitely randomly seen submodule issues at times when switching branches and what not, so its useful still in those scenarios for people
There was a problem hiding this comment.
Please leave this documentation and fill out this line in the table
captainsafia
requested review from
mkArtakMSFT,
Pilchie,
dougbu,
wtgodbe and
HaoK
Pilchie
added
the
area-infrastructure
docs/README.md
Outdated
| | [Working with EventSources and EventCounters](EventSourceAndCounters.md) | Guidance on adding event tracing to a library | Contributors needing to add event tracing for diagnostics purposes | | ||
| | [Tests on Helix](Helix.md) | An overview of the Helix test environment | Contributors debugging tests in Helix or looking to understand the output from Helix builds | | ||
| | [Issue management](IssueManagementPolicies.md) | Overview of policies in place to manage issues | Community members and collaborators looking to understand how we handle closed issue, issues that need author feedback, etc | | ||
| | [Package archives](PackageArchives.md) | | | |
There was a problem hiding this comment.
This document and the entry for it should be removed from the 'master' branch. It's not relevant in our newer branches.
docs/README.md
Outdated
| |--------------------------------------------------------------------------|-------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------| | ||
| | [API review process](APIReviewProcess.md) | Outlines the process for reviewing API changes in ASP.NET Core | Anyone looking to understand the process for making API changes to ASP.NET Core | | ||
| | [Artifacts structure](Artifacts.md) | Outlines the artifacts produced by the build | Anyone looking to understand artifiacts produced from an Azure DevOps build | | ||
| | [Troubleshooting build errors](BuildErrors.md) | Common errors that occur when building the repo and how to resolve them | Anyone running into an issue with the build locally | |
There was a problem hiding this comment.
| | [Troubleshooting build errors](BuildErrors.md) | Common errors that occur when building the repo and how to resolve them | Anyone running into an issue with the build locally | | |
| | [Troubleshooting build errors](BuildErrors.md) | Common errors that occur when building the repo and how to resolve them | Anyone running into an issue with the build | |
(Some errors may also occur on the CI)
docs/README.md
Outdated
| @@ -1,11 +1,27 @@ | |||
| Contributor documentation | |||
| Documentation Field Guide | |||
There was a problem hiding this comment.
Recommend undoing this change. "Contributor documentation" is correct and a bit less cutesy
docs/README.md
Outdated
| | [Building from source](BuildFromSource.md) | Setup instructions for the ASP.NET Core repo | First-time contributors | | ||
| | [Working with EventSources and EventCounters](EventSourceAndCounters.md) | Guidance on adding event tracing to a library | Contributors needing to add event tracing for diagnostics purposes | | ||
| | [Tests on Helix](Helix.md) | An overview of the Helix test environment | Contributors debugging tests in Helix or looking to understand the output from Helix builds | | ||
| | [Issue management](IssueManagementPolicies.md) | Overview of policies in place to manage issues | Community members and collaborators looking to understand how we handle closed issue, issues that need author feedback, etc | |
There was a problem hiding this comment.
Stick with "Contributors" throughout this table. "Community members" and "collaborators" aren't useful distinctions here.
There was a problem hiding this comment.
IMO, community members = people who use ASP.NET even if they don't contribute to it
Contributors = People who make code/docs contributions to ASP.NET
Collaborators = People with collaborator rights (aka responsible for review, servicing work, build ops, etc)
There was a problem hiding this comment.
I agree we could make those distinctions. But, drawing the lines does not sound inclusive to me. Everyone contributes in different ways and the "looking to" bits are enough explanation.
docs/README.md
Outdated
| | [How references are resolved](ReferenceResolution.md) | Overview of dependency reference setup in the repo | Contributors looking to understand how package references are configured in the repo | | ||
| | [Servicing changes](Servicing.md) | Documentation on how to submit servicing PRs to previous releases | Collaborators to submit patches or backports to prior releases, contains the "Shiproom Template" | | ||
| | [Shared framework](SharedFramework.md) | Overview of the ASP.NET Core Shared framework | Contributors looking to understand the policies in place for managing the code of the shared framework | | ||
| | Submodules | | | |
There was a problem hiding this comment.
Please leave this documentation and fill out this line in the table
docs/README.md
Outdated
| - [Artifacts structure](Artifacts.md) | ||
| The table below outlines the different docs in this folder and what they are helpful for. | ||
|
|
||
| | Documentation | What is it about? | Who is it for? | |
There was a problem hiding this comment.
nit: The extra spaces make this harder to read the source. They also don't change the table layout. Suggest
| | Documentation | What is it about? | Who is it for? | | |
| | Documentation | What is it about? | Who is it for? | |
and so on for all rows
Adding docs about our docs. 😆