Suggestions for General Improvements to Documentation Presentation

[cseguenot]

Currently, the format of the documentation for ASP.NET and other technologies is off-putting and does not facilitate understanding of your technologies. This could hinder their adoption, especially for Blazor.
Below are my suggestions, partly discussed and shared by the Blazor community on Reddit.

Page Length

Some pages are far too long. For example, the page on navigation and routing contains over 7,300 words—equivalent to 35 A4 pages (measured in Word).

→ Break down large pages into smaller, more digestible ones (max 3,000 words).

Headings

H2 and H3 headings are not numbered, and their styles are nearly identical. This makes it difficult to navigate the page and clearly see its structure.

→ Number the headings and use sufficiently different colors and font sizes for H2 and H3 levels.

Navigation

Side Navigation Panel

The side navigation panel can display up to four levels of nesting but lacks any visual distinction between these levels, making it hard to see where the current page is located in the hierarchy.

→ Bold the current item at each level. For example, for a page with the path Web apps / Blazor / Fundamentals / Routing and navigation, bold each component of this path and use a light yellow background for the last component to make it stand out. Use a larger font for the first level.

→ Make the panel collapsible so the documentation page can be displayed with sufficient width when, for instance, the browser and Visual Studio windows are side by side.

Breadcrumb Navigation

The breadcrumb displayed at the top of each page is currently of little use. For example, for the path above, the breadcrumb shows: Learn / .NET / ASP.NET Core /.

→ Display the full page path in the breadcrumb (without "Learn") and in a larger font:
.NET / ASP.NET Core / Web apps / Blazor / Fundamentals /

Clicking on a segment could take the user to the Overview page of the corresponding section.

With this breadcrumb, you could remove "ASP.NET Core Blazor" from the H1 title of each page, improving conciseness and clarity.

Previous/Next Page Navigation

→ At the bottom of each page, add links to the previous and next pages based on the order defined in the left navigation panel. This would greatly improve page-to-page navigation.

Illustrations

The documentation currently consists only of text and code, with no diagrams or images. This makes the pages less engaging and harder to understand. Humans are visual learners—we appreciate variety, colors, and visuals, which help us grasp and retain information better.

→ Add diagrams and screenshots to clarify concepts and make the pages more pleasant to read. It would be perfectly acceptable to leave the text inside diagrams untranslated to simplify their management.

Translation

Machine-translated documentation in other languages (at least for French) is currently very poor. It forces users to constantly switch back to English. Learning and understanding complex concepts already requires significant effort, so having reliable documentation in one's native language would be a huge help.

→ Significantly improve the quality of translations. Note: DeepSeek excels at translation.

Conclusion

I hope you understand that this is not just about aesthetics. Documentation is not a minor detail—it is one of the most critical elements in making a technology accessible, understandable, and encouraging its adoption.
For example, I find Blazor extraordinary, but its documentation is discouraging, and I’m far from the only one who feels this way. Improving the documentation would, in turn, improve Blazor’s adoption.

[guardrex]

Hello @cseguenot ... Thanks for the feedback. I'll take a look at this and respond tomorrow (Monday) morning. I was going to respond after July 4th, but it won't take very long to respond. Many of the items you bring up aren't controlled here by us ... they're decisions that are made by managers and apply to all documentation sets at Microsoft, so I'll need to tell you where you can open the feedback for those items. On a few other items that we do control, the approach taken is by-design, and I can give you the reason(s). On at least one item, the length of the Blazor Routing fundamental article, I'll take a look at breaking it up into a node (folder) of articles. I'll get back to you tomorrow morning.

[poremba]

Arriving here from this discussion: https://www.reddit.com/r/Blazor/comments/1ll5wtf/microsofts_documentation_is_really_starting/

Back in the day (last century) Microsoft was an industry leader in no small part due to excellent documentation, richly detailed error messages to help with debugging, and great code samples and example projects available on MSDN or later online.

Back then, technical writers and UX experts were more commonplace across the industry. Now two generations later, software engineers are commonly expected to produce all of the documentation at the tail end of a project, after they wrap up their code and before they rush off to ship code for another project.

Check with those managers about who they think actually owns the documentation at Microsoft, or even just for this product, and what support those owners will need to produce more useful documentation. Perhaps this docs team needs better support at a corporate level, or more staffing to handle the doc volume that a great product deserves in order to take off.

Some companies today still do create excellent documentation. Many of the most successful products, either open source or closed commercial, partly owe that success to providing rich documentation to grow the user base. My expectation is that such results are deliberate outcomes, requiring staff dedicated to—and held responsible for—docs, code samples, and error messages. Microsoft was once a facto leader in this across all of the product lines. Totally doable—given the right organizational support.

[guardrex]

Thanks @poremba for the cross-link.

We've occasionally seen issues here and external discussions like that over the years, and we do have answers, including a few disagreements with some community members on a few points.

Some of that discussion (and this issue) aren't directly controlled by us here. Microsoft docs are compartmentalized at the product/service level and between the content and the overall UI. We only directly control the content. By "content," I mean the text, images, layout (ToC and section ordering only), and samples. We have little to no direct control over the UI and localization. Decisions on those aspects are controlled by other teams and docs management.

For the items that are mentioned in the Reddit discussion and this issue that we don't control (e.g., breadcrumbs, font sizes, UI hints, etc.), I'll explain where community members can provide feedback.

BTW ... The API Browser is a separate system. Content is built from the framework API, so an issue opened for the ASP.NET Core product unit makes the most sense if API Browser content seems incorrect or poorly worded. The layout of that UI, however, isn't controlled by our product unit.

Stand-by for a more detailed response on the particulars of this issue and the Reddit discussion. I'll get back to you here tomorrow morning.

[guardrex]

Whooops! I had something come up this morning that I had to attend to. Give me a few hours ... I'll respond here by EOD. 🏃‍♂😅

[guardrex]

I'm BACK! 😄 ... a bit late🌛... I've been on the run all day. It was the last day of my vacation.

I'll respond on translation first and ping a couple of 🐱🐱 on the CEIC team, which is the MS localization team, and then I'll respond to the rest.

[guardrex]

On Translation, I can ping @khoiph1 and @kgliang to take a look.

Khoi and/or Kevin, can you please take a look at the Translation entry of the OP here for feedback from @cseguenot on MS Learn translation?

[guardrex]

Items that we don't control here

The following pertain to the entire Learn site and aren't controlled here.

@wadepickett @tdykstra ... The MS Docs feedback repo issues at MicrosoftDocs/feedback GH repo is mothballed. Since we don't have the "standard experience" feedback available for our doc set, can you say how @cseguenot can get his feedback filed with management on ...

• Headings
• Navigation: Side Navigation Panel
• Navigation: Breadcrumb Navigation

Items that we control but that are by-design

@wadepickett and/or @tdykstra might have additional insights into these. I'll comment on these, and they'll say if they feel differently about anything.

Previous/Next Page Navigation

By convention, we only use previous/next page navigation elements in tutorials. The team will decide if they would like to institute it on a wider basis. Blazor docs will abide by whatever convention they adopt for the main doc set.

Illustrations

By convention, we only generally use images in tutorials. We don't use many images elsewhere for two main reasons. The first reason is more important than the second, but they're somewhat related ...

1. Localization: Images are often screenshots of either app-rendered UIs or tooling, and it would only be possible for us to produce them broadly in English. We don't have the capacity to localize image language content. There are some web-based diagram technologies out there that might be loc capable, but we haven't been advised by management to adopt them.
2. Cost: The staffing isn't available to create and maintain many images, even if such images didn't contain text. They're time-consuming to create and maintain, and we can barely keep up with the workload here ... well ... I'll speak for myself and Blazor docs anyway. I'm always ⛰⛏😅 with a thousand things to do. Personally, I wouldn't have the time to add many images to articles, even if loc wasn't a problem. MS would have to hire more 🦖🦖🦖🦖😆 if it was decided that we should look for every opportunity to use images. I'll definitely consider them on a case-by-case basis. A reader should open an issue for an article if they think an image (or several) would be particularly helpful.

Page Length

This is an on-going work item for us. Articles grow over the years. Eventually, many of them reach a critical mass ☢ ... and then they 💥 with readers wishing to be able to consume content in a more bite-size fashion with a set of shorter articles that each contain related content.

The Routing and Navigation article has probably reached that point 💥. I opened #35683 to address it. We'll either split it in the Fundamentals node into a folder of articles with an overivew, or we'll leave a single, shorter article in the Fundamentals node that only covers the basics of routing and nav with an advanced article elsewhere in the ToC. I'm discussing it with management offline now.

Conclusion

I hope you understand that this is not just about aesthetics. Documentation is not a minor detail—it is one of the most critical elements in making a technology accessible, understandable, and encouraging its adoption.

You don't need to hope that we understand that. We 100% agree. 👍

For example, I find Blazor extraordinary, but its documentation is discouraging ...

"Discouraging" isn't actionable, and I can't tell if you're referring to content or UI UE (user experience) factors that you listed. When referring to content, I would need more details, probably issues for specific articles with specific feedback.

Reddit discussion

I'll analyze and react to Reddit discussion comments soon on this thread. I'll try to do that tomorrow, but I'm returning from vacation and might be swamped tomorrow. I'll try to respond this week for sure.