We Need Your Feedback on the Documentation


 

image The doc teams are looking for your feedback on the .NET Framework and Visual Studio docs.  Help us improve the developer documentation by taking the Visual Studio and .NET Framework Content Survey.  This survey will give us a better understanding of the type of applications you are developing as well as how you use Help and how we can improve it. The survey takes only 10 minutes, and we really appreciate your feedback! Feel free to forward the survey link.

Comments (9)

  1. Ravi says:

    The online docs that popup e.g when pressing F1 over a .NET native class such as the List collection, I find, are quite abstract and would be great with a few more examples of their use.

  2. Juan Zamudio says:

    What i would love to see is a way to know if an Win API has a managed alternative,  for example I use WNetAddConnection2W to connect to a network share and I want to enter a page, search the API and see the managed libraries I can use instead the Win API.

  3. MikeS says:

    EXAMPLES, EXAMPLES, EXAMPLES, EXAMPLES… sorry, went all ballmerish there 😉

    Seriously, though, MSDN is in dire need of realistic samples – not just the minimal code showing how to new up a class and call an obvious method with obvious params. What’s needed is actual use cases – how-to achieve real results with the framework.

    Also, much more in depth high-level overviews of each class is needed, with preconditions, gotchas etc. fully documented.

  4. BarryB says:

    Context – API’s that work together need to be documented together so it’s clear how they are used together–but not in some huge monolithic application that takes months to figure out.

    Also, when cross-linking documentation snippets, make sure they are meaningful in every context they show in. This is often not the case.

    Completeness – Document and provide examples for all arguments for an API, not just the simple, straight forward ones.

    Consistency – Don’t use washed out C programmers to write managed code samples. Code samples should be consistent with the design of the language and technology.

    Document code samples – There is little more useless to a novice (and often more experienced ) developer than a page of undocumented code that is supposed to be exemplifying something complex.

    Provide contextual direction – Include where and when an api is intended to be used. For example, there are a number of namespaces in the .Net framework that represent simplified abstractions of other namespaces but it isn’t always clear when looking at the documentation for an API that this is the case or where in the hierarchy the particular api falls. A good example of this is the multi-threading api’s, but there are many others.

    Accuracy – Improve the integration between UE and Development teams. It’s not reasonable to expect good technical writers to also be technology experts. It should be reasonable to expect the documentation to be accurate and descriptive of, and a clear explanation of, the technology.

  5. Denny says:

    I am in-line with the other comments:

    much of the help is no help at all.  it’s just the parameters listed and nothing or very little about *WHY* this method is usefull.

    also sometimes we need more info about *HOW* a given class / method / function behaves.

    esp. this is true with the more arcane classes and methods.

    there are some real gems in there *IF* you know where to find them.

    finding a list of classes and namespaces tells me next to nothing about which ones to look at for a given job.

    for example how to bring to gether IO.File and Stream to do some common file processing tasks.

    or how some parts of the Serial Port class should be used.   having to experiment with datetime.parse to figure out which formats it gets right and which it does not.

    and if i need to parse a given date time what’s the best way?   can i use the iFOrmat***  fast or do i just use string.Split() and be done with it?

  6. AndyF says:

    I completely concur with BarryB’s comments – he has well-stated the shortcomings and wish list items for MS documentation.  However, I would also add…

    For years I did work in Visual FoxPro and if you want to see GOOD documentation, go back and look at the VFP documentation.  It was useful, usable, and written clearly by professional documentors who provided great examples, links and related materials references.  It was GREAT stuff.

    Most of the VS and SQL documentation is completely useless and a waste of valuable time.  Around our company we joke that the MS documentation was written by MS experts for MS experts – not for the general VS/SQL consuming public.  Such an oversight is an outrage, if not a classic example of where intelligence, no matter how vast, trumps common sense.  And that is what most recent MS documentation lacks almost totally – common sense.

    There needs to be a mantra from MS product documentors and that should be "We are writing this for our customers – NOT our fellow employees…"  If they chant this 1000 times per hour until they get it, that would be a good thing.

  7. SittButt says:

    In general, the code sample are very simple, made it more complicated and ground on real world use … forget the Hello World … it’s boring and that’s did’nt help people.

    Try to focus on work utilisation of sample code.

    Always the code we make a rellay more sophisticated than the basic sample of 5 lines you insert in sample.

  8. Peter Wone says:

    And finally it works! You’ll see this same text elsewhere, I was having trouble with the captcha image…

    Examples are certainly essential, but I think that even more important is context.

    Your own Framework Design Guidelines book explains how a framework must be coherent. That coherence is contextual, and key to understanding and correctly using the framework is understanding the terms in which it is conceived.

    Existing walkthroughs go some way to addressing this but you could formalise it and make it a lot more extensive with a "Theory of operation" section similar to electronics project kit instructions.

    Every topic that serves a particular purpose (eg I/O) should have a prominent link (up the top not buried at the end) to "Theory of operation".

  9. Peter Wone says:

    Further on "Theory of operation" and design guidelines etc, you’ll recall from your own book that IO APIs exist at several levels of abstraction. It would be extremely helpful in such situations if the documentation described the details and relationship between all such modes of use, discussed appropriate application of them and clearly showed which model applies to which methods and classes.