# How Documentation Content Is Organized in the ASP.NET Core Docs Folder

> Discover how ASP.NET Core documentation content is organized within the docs folder. Learn about the flat structure and topic-based grouping of Markdown files for clarity.

- Repository: [.NET Platform/aspnetcore](https://github.com/dotnet/aspnetcore)
- Tags: internals
- Published: 2026-08-01

---

**The `docs` folder in the `dotnet/aspnetcore` repository employs a flat structure where Markdown files with self-describing names are grouped by topic rather than nested in subdirectories.**

The `dotnet/aspnetcore` repository centralizes its contributor and developer guidance inside a single `docs` directory at the repository root. Rather than employing a deep hierarchy of subfolders, the **documentation content organized in the `docs` folder** follows a flat architectural pattern where each Markdown file addresses a discrete topic, making discovery straightforward for contributors and maintainers.

## Flat Architecture and Naming Conventions

All documentation resides at the root of `docs/` without nested subdirectories. This design choice eliminates navigation overhead—contributors can scan the directory listing to locate relevant guidance. The repository follows a strict convention of **descriptive filenames** that indicate content type, such as [[`BuildFromSource.md`](https://github.com/dotnet/aspnetcore/blob/main/BuildFromSource.md)](https://github.com/dotnet/aspnetcore/blob/main/docs/BuildFromSource.md) for compilation instructions or [[`APIReviewProcess.md`](https://github.com/dotnet/aspnetcore/blob/main/APIReviewProcess.md)](https://github.com/dotnet/aspnetcore/blob/main/docs/APIReviewProcess.md) for governance workflows. A single image asset, `vs-iis-express-aspnet-core-mvc-sandbox.jpg`, provides visual support for specific guides.

## Categorical Organization of Documentation Files

While physically flat, the files logically cluster into several functional domains based on their naming and content focus.

### Build and Development Guides

Files such as [[`BuildFromSource.md`](https://github.com/dotnet/aspnetcore/blob/main/BuildFromSource.md)](https://github.com/dotnet/aspnetcore/blob/main/docs/BuildFromSource.md) and [[`BuildErrors.md`](https://github.com/dotnet/aspnetcore/blob/main/BuildErrors.md)](https://github.com/dotnet/aspnetcore/blob/main/docs/BuildErrors.md) contain instructions for compiling ASP.NET Core from source and troubleshooting compilation failures. These documents target new contributors and developers preparing custom builds.

### Feature Implementation Tutorials

Step-by-step instructions for specific capabilities are captured in files like [[`Trimming.md`](https://github.com/dotnet/aspnetcore/blob/main/Trimming.md)](https://github.com/dotnet/aspnetcore/blob/main/docs/Trimming.md) for assembly trimming and [[`WebTransport.md`](https://github.com/dotnet/aspnetcore/blob/main/WebTransport.md)](https://github.com/dotnet/aspnetcore/blob/main/docs/WebTransport.md) for HTTP/3 WebTransport implementation. These guides provide technical depth on advanced features.

### Governance and Process Policies

Internal workflows are documented in [[`APIReviewProcess.md`](https://github.com/dotnet/aspnetcore/blob/main/APIReviewProcess.md)](https://github.com/dotnet/aspnetcore/blob/main/docs/APIReviewProcess.md), [[`TriageProcess.md`](https://github.com/dotnet/aspnetcore/blob/main/TriageProcess.md)](https://github.com/dotnet/aspnetcore/blob/main/docs/TriageProcess.md), and [[`IssueManagementPolicies.md`](https://github.com/dotnet/aspnetcore/blob/main/IssueManagementPolicies.md)](https://github.com/dotnet/aspnetcore/blob/main/docs/IssueManagementPolicies.md). These files define how the team reviews public APIs, triages bugs, and manages incoming issues.

### Engineering Tooling and Maintenance

Documentation covering internal tooling resides in [[`tooling-consolidation.md`](https://github.com/dotnet/aspnetcore/blob/main/tooling-consolidation.md)](https://github.com/dotnet/aspnetcore/blob/main/docs/tooling-consolidation.md) and [[`UpdatingMinifiedJsFiles.md`](https://github.com/dotnet/aspnetcore/blob/main/UpdatingMinifiedJsFiles.md)](https://github.com/dotnet/aspnetcore/blob/main/docs/UpdatingMinifiedJsFiles.md). Reference resolution guidance is provided in [[`ReferenceResolution.md`](https://github.com/dotnet/aspnetcore/blob/main/ReferenceResolution.md)](https://github.com/dotnet/aspnetcore/blob/main/docs/ReferenceResolution.md).

### Release Management and Servicing

Versioning and distribution processes are detailed in [[`ReleasePlanning.md`](https://github.com/dotnet/aspnetcore/blob/main/ReleasePlanning.md)](https://github.com/dotnet/aspnetcore/blob/main/docs/ReleasePlanning.md), [[`Servicing.md`](https://github.com/dotnet/aspnetcore/blob/main/Servicing.md)](https://github.com/dotnet/aspnetcore/blob/main/docs/Servicing.md), and [[`SharedFramework.md`](https://github.com/dotnet/aspnetcore/blob/main/SharedFramework.md)](https://github.com/dotnet/aspnetcore/blob/main/docs/SharedFramework.md). These documents outline the cadence for releases and servicing updates.

### Community Ownership and Onboarding

The [[`area-owners.md`](https://github.com/dotnet/aspnetcore/blob/main/area-owners.md)](https://github.com/dotnet/aspnetcore/blob/main/docs/area-owners.md) file maps functional areas of the codebase to their respective maintainers, while [[`OnboardingNewOS.md`](https://github.com/dotnet/aspnetcore/blob/main/OnboardingNewOS.md)](https://github.com/dotnet/aspnetcore/blob/main/docs/OnboardingNewOS.md) provides guidance for adding support for new operating system platforms.

### Diagnostic References

[[`list-of-diagnostics.md`](https://github.com/dotnet/aspnetcore/blob/main/list-of-diagnostics.md)](https://github.com/dotnet/aspnetcore/blob/main/docs/list-of-diagnostics.md) serves as a catalog of analyzer diagnostics and error codes used throughout the framework.

## Programmatic Access to Documentation

Since the structure is flat and predictable, scripts can easily consume these files using standard file system APIs.

Reading a documentation file from a C# script:

```csharp
using System;
using System.IO;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        // Path is relative to the repository root
        var path = Path.Combine("docs", "Trimming.md");
        if (File.Exists(path))
        {
            var content = await File.ReadAllTextAsync(path);
            Console.WriteLine($"First 200 characters of Trimming.md:\n{content[..200]}");
        }
        else
        {
            Console.WriteLine("Documentation file not found.");
        }
    }
}

```

Listing all documentation files with bash:

```bash
#!/usr/bin/env bash

# Print a concise list of Markdown files in the docs folder

printf "Docs in the repository:\n"
find docs -maxdepth 1 -name "*.md" -printf " - %f\n"

```

## Summary

- The `docs` folder employs a **flat hierarchy** with no subdirectories, placing all files directly under `docs/`.
- Files use **self-describing names** like [[`BuildFromSource.md`](https://github.com/dotnet/aspnetcore/blob/main/BuildFromSource.md)](https://github.com/dotnet/aspnetcore/blob/main/docs/BuildFromSource.md) and [[`APIReviewProcess.md`](https://github.com/dotnet/aspnetcore/blob/main/APIReviewProcess.md)](https://github.com/dotnet/aspnetcore/blob/main/docs/APIReviewProcess.md) to indicate content type.
- Documentation spans categories including **build instructions**, **feature guides**, **process policies**, and **release management**.
- A single image file (`vs-iis-express-aspnet-core-mvc-sandbox.jpg`) supports visual documentation needs.
- The structure enables simple programmatic discovery using standard file system APIs.

## Frequently Asked Questions

### Are there any subdirectories within the ASP.NET Core docs folder?

No. According to the source code structure, the `docs` directory contains only Markdown files and a single image asset at its root. The repository intentionally avoids nested folders to maximize discoverability and reduce navigation friction for contributors.

### How do I determine which team owns a specific area of ASP.NET Core?

Consult the [[`area-owners.md`](https://github.com/dotnet/aspnetcore/blob/main/area-owners.md)](https://github.com/dotnet/aspnetcore/blob/main/docs/area-owners.md) file. This document maintains a mapping between functional areas—such as MVC, SignalR, or Security—and the GitHub usernames of the engineers responsible for triage and code review in each area.

### What file should I read to learn about building ASP.NET Core from source?

The [[`BuildFromSource.md`](https://github.com/dotnet/aspnetcore/blob/main/BuildFromSource.md)](https://github.com/dotnet/aspnetcore/blob/main/docs/BuildFromSource.md) file provides comprehensive instructions for compiling the framework, including prerequisite installations and command-line workflows. For troubleshooting compilation failures, refer to [[`BuildErrors.md`](https://github.com/dotnet/aspnetcore/blob/main/BuildErrors.md)](https://github.com/dotnet/aspnetcore/blob/main/docs/BuildErrors.md).

### Does the docs folder contain any non-text assets?

Yes. In addition to Markdown files, the folder includes one image file named `vs-iis-express-aspnet-core-mvc-sandbox.jpg`. This asset supplies screenshots or diagrams referenced by specific development and debugging guides.