Comment by oaxacaoaxaca | Hacker News Reader

Comment by oaxacaoaxaca | Hacker News Reader

Parent Full thread

Not "struggling in other areas" but thanks.

Been using VS and VSCode for a long time.

Don't care that the docs are open source.

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)

Hi. Sure thing.

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

No negativity received on this end at all!

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.

Hey thanks! I hadn't gone through that site, but I'm reading https://docs.microsoft.com/en-us/learn/modules/build-web-api... now. Looks great! Nice work!

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).

Reply on news.ycombinator.com