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.
A quick example could be user authentication:
https://docs.djangoproject.com/en/2.2/topics/auth/default/ https://docs.microsoft.com/en-us/aspnet/core/security/author...
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.