Amazon.com Widgets

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.

Published 30 October 09 09:49 by BradA
Filed under:

Comment Notification

If you would like to receive an email when updates are made to this post, please register here

Subscribe to this post's comments using RSS

Comments

# Ravi said on October 30, 2009 1:51 PM:

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.

# Juan Zamudio said on November 1, 2009 1:22 AM:

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.

# MikeS said on November 1, 2009 7:04 AM:

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.

# BarryB said on November 1, 2009 8:49 AM:

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.

# Denny said on November 1, 2009 8:50 AM:

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?

# AndyF said on November 5, 2009 8:28 AM:

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.

# SittButt said on November 6, 2009 12:29 PM:

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.

Leave a Comment

(required) 
(optional)
(required) 

  
Enter Code Here: Required

Search

This Blog



These postings are provided "AS IS" with no warranties, and confer no rights.



Ads by Lake Quincy Media

Syndication

Page view tracker