Share via

We Need Your Feedback on the Documentation

  • Article

 

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

  • Anonymous
    October 30, 2009
    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.

  • Anonymous
    October 31, 2009
    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.

  • Anonymous
    October 31, 2009
    The comment has been removed

  • Anonymous
    November 01, 2009
    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.

  • Anonymous
    November 01, 2009
    The comment has been removed

  • Anonymous
    November 05, 2009
    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.

  • Anonymous
    November 06, 2009
    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.

  • Anonymous
    December 10, 2009
    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".

  • Anonymous
    December 10, 2009
    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.