Lars Kemmann

My feedback

  1. 249 votes
    Vote
    Sign in
    (thinking…)
    Sign in with: facebook google
    Signed in as (Sign out)
    You have left! (?) (thinking…)
    4 comments  ·  General ASP.NET » General ASP.NET  ·  Flag idea as inappropriate…  ·  Admin →
    Lars Kemmann commented  · 

    By the way, here's the issue where it's being tracked: https://github.com/SignalR/SignalR/issues/372

    Lars Kemmann commented  · 

    This is also essential for using SignalR in a web worker context (no DOM = no ability to load jQuery).

    Lars Kemmann supported this idea  · 
  2. 6 votes
    Vote
    Sign in
    (thinking…)
    Sign in with: facebook google
    Signed in as (Sign out)
    You have left! (?) (thinking…)
    2 comments  ·  Show me how with code  ·  Flag idea as inappropriate…  ·  Admin →
    under review  ·  Rick Anderson responded

    We no longer use MSDN for anything but reference (type information). the asp.net site is where we do this now.

    Lars Kemmann commented  · 

    And you know (since I just noticed that this post has been moved from its original context of ASP.NET vNext), I would say it's very telling that your team has *an entire UserVoice forum* essentially dedicated to requests for better documentation.

    Maybe I'm naïve and I don't understand what's going on. But take a moment to hear a naïve developer, please. :)

    You really need to address this problem systematically, rather than trying to catch up with piecemeal requests for particular scenarios. Tutorials might look like the best solution for any given issue, but documentation *is a solved problem* for most of the rest of the .NET Framework. When your documentation provides complete understanding of how to use a particular framework, the concepts involved, and guidance around how to combine different related pieces, then the tutorials can really be more of an afterthought.

    The reason you get so many requests in this forum for "the latest/greatest/complete/best/right way to do X" (aside from lack of resources on your team, that's evident :)) is that we fundamentally *do not trust* introductions and tutorials! We have been taught, since high school or earlier in many cases, that "tutorial" = "intentionally simplified situation-specific version of the truth." Can you blame enterprise-grade and cloud-scale teams for not wanting to bet their business on what might or might not be included in a tutorial?

    When I read a tutorial and implement code as I follow it, the first thing I do is read all the IntelliSense and MSDN documentation on the types & methods I'm using so that I get an in-depth understanding of the effect my code is having. In fact, if I introduce usage of a new API and I can't fully defend or explain it, that code *fails in peer review.* I can't be the only one in that boat.

    Okay, end of rant. I really do care about this. :) Bottom line: Instead of trying to keep up with one-off tutorials in an ever-expanding scope, I suggest you focus on providing *composable documentation* (there, I even made up a buzzword to help you sell the concept :)).

    Lars Kemmann commented  · 

    Thanks for the response! That makes me sad... I had always held out hope that the paltry ASP.NET documentation was just a result of ongoing shifts in the platform and it would eventually be addressed. :(

    Would it be possible to do two things then:
    1. Add a prominent note to the MSDN "overview" pages (see link in the original post) that clearly calls this out, so there's no confusion for the average .NET developer (who has mostly relied on MSDN in the past). The simple fact that there are links to www.asp.net alone doesn't communicate the fact that that is essentially the replacement for MSDN in the ASP.NET space.
    2. Actually provide complete documentation on the ASP.NET site.

    In other words, I understand (well, not really, but I don't mind) the fact that you've decided to abandon MSDN for www.asp.net. However, that doesn't solve the underlying problem of poor documentation quality. I get that it's "on par" with many competing frameworks these days, but you ought to do much better.

    And in addition, the "type information" on MSDN is still extremely sparse. There is no guidance on how to use the types properly. At least that part is generated from the open-source XMLdocs, right? So there's a vague hope...

    Lars Kemmann shared this idea  · 

Feedback and Knowledge Base