I’ve gone straight to the official Microsoft docs multiple times to try and get the same experience as when you read the Django documentation, but it’s just not there. Django’s docs explain the what, the why, and more. The Microsoft docs just have the what.
I want to love .NET Core development because I love Microsoft’s open source effort, but the support (or lack thereof) from the documentation is quite the hindrance.
My issue is that I guess I have high expectations for the official docs of a platform/framework/library/whatever. You shouldn't have to buy a book or read a random blog to find critical information on core functionality. The official docs should provide that, and Django is a great example. It includes how to do things, why things are the way they are, how to customize workflows, best practices, pitfalls, and on top of all that the source code is super easy to read and understand.
The pages at docs.microsoft.com are mostly just basic walkthroughs that leave me with a lot of questions. And the .NET Core source code is not nearly as readable.
It's getting better though. And I don't mean to take jabs at Microsoft because I truly do appreciate how much they've done in open source over the last few years, especially with VSCode.
Do you have a concrete example or two from the Django docs that you consider to be representative? Not doubting you at all; honestly just curious to see what you're looking for in documentation.
Microsoft docs are constantly under revision, including general improvements (not just reaction to changes), and the writers are very receptive and responsive to feedback.
(I work at Microsoft on docs, but not on the ASP.NET Core docs)
First off, thank you for what you do. Microsoft is kicking ass these days and I don't want to sound like I'm unappreciative or unimpressed with what you guys are doing.
The first thing I see when scrolling down those pages is that the Django page is ~90% descriptive text and ~10% code. The ASP.NET page is the opposite: ~10% descriptive text and ~90% code.
Obviously that's not the best metric but I need to get off HN soon so that's the best I have for now :)
In any case, this could support my earlier claim: Django docs give not just the "what" – they also provide the "why", along with super useful background/supporting information, and even alternative approaches (e.g. in the "Limiting access to logged-in users" section there are at least five avenues you can choose from to meet your needs).
That was the quickest example I could find. Sorry it's not more substantive. I'll post again later if I find something that could be more helpful.
And again, I really appreciate what you guys are doing and don't mean to sound like I'm sending any negativity in your direction <3
I definitely see what you're saying - that section of the ASP.NET Core docs drop straight into a top-to-bottom code-driven tutorial, whereas the Django docs go concept-by-concept. This is great feedback, so thanks!
If you get a chance, check out Microsoft Learn (microsoft.com/learn) - we're working on guided learning as opposed to documentation. Most of our content is interactive and task-based, but we try to ground the interactivity with conceptual information, context and scenarios. Much of the technical content published to date is Azure-focused, but we're growing other topics, including ASP.NET Core.
Although improving recently, Microsoft still struggles with "our docs contain lots of knowledge but not a lot of wisdom." I go to documentation to find wisdom about the whys and why nots, not just the hows (i.e., method signatures and syntax).
I want to love .NET Core development because I love Microsoft’s open source effort, but the support (or lack thereof) from the documentation is quite the hindrance.