Jaa

Brutal Honesty

  • Artikkeli

I guess it's time to admit what I do for my day job here at Microsoft. Sadly I don't get to play with SPOT watches and digital cameras every day (and that's the story we're all going to be telling my manager, right?). Well, my title is “Programmer/Writer”, and I work on the Visual Studio C# documentation team creating new content and dreaming up ways to help you folks - the programmers that use C# - get the information you need.

So, since I've been so honest, now it's your turn. If you had the opportunity to improve the coverage of one area in the current C# documentation, what would it be? What topic would like you see explained in more detail? Would you like more documentation about the C# language itself, or more examples of applications of the language? How useful do you find large project walkthroughs compared to short code examples?

Documentation can be a tricky thing to get feedback on - many people will just say "Google" when I trap them in a corner and ask them where they get their C# help from, but often Google just points right back at MSDN and the content I write. So, forget finding the content for the moment, and tell me what type of content you like to see..

Cheers!

Comments

  • Anonymous
    March 01, 2004
    I'd like to see somebody fix the Visual Studio .NET documentation for

    systemwebuiwebcontrolscalendar_1.rtf, TodayDayStyle Property

    where it states that "If the TodayDayStyle property is not set, the style specified in the DayStyle property is used." This is actually incorrect. In reality, the calendar control uses its own internal default values for TodayDayStyle, making it impossible for the developer to specify a CssClass for the style because the default style values override the assigned CssClass. As a result, I had to rewrite the entire Calendar control from scratch so I could specify a CssClass for the TodayDayStyle.
  • Anonymous
    March 01, 2004
    Document the undocumented fatures of the framework. Document the classes required for aspect oriented programming. IMessageSink etc
  • Anonymous
    March 01, 2004
    Include more information about the tougher interfaces in teh framework like ITypedList. ITypedList is hardly documented, but very important if you want to write custom classes which have to support complex databinding. Also IEditableObject comes to mind.

    Also include more information about complex databinding, how it works and what to do in your own code to make your code be able to be used in a complex binding scenario. Now documentation only includes the basic, non interesting scenarios. Like: when to use your own currencymanager, how to create read-only properties at runtime in a databinding scenario for code which does have read/write properties.
  • Anonymous
    March 01, 2004
    programming guidelines applied, not forgotten - it's so simple...
  • Anonymous
    March 01, 2004
    First of all, thanks for the great documentation that comes with the .NET framework. I knew I had some gripes with a particular documenetation issue recently, but I had to dig deeply to find what it was again.

    But I found it:

    There are several methods/properties whose return value is only specified for success situations, but not for failure situations. One example is the property System.Text.RegularExpressions.Capture.Value (inherited by the Group and Match classes). Its documentation reads 'Gets the captured substring from the input string'. Great. But what does it return when the capture/group/match did not succeed (Group.Success==false)? Does accessing 'Value' (a) throw an exception, (b) return an empty string, (c) return null ?. The empirically found answer seems to be (b). But I had to write a little test to find that out.

    There are several other places where values in situations that don't throw an exception but are somehow exceptional are undocumented.
  • Anonymous
    March 01, 2004
    The comment has been removed
  • Anonymous
    March 02, 2004
    BTW, C# documentation is distinct from .NET Frameworks documentation.

    But thanks for all the comments so far!
  • Anonymous
    March 04, 2004
    Language Filter button on the docs online, too
  • Anonymous
    April 27, 2004
    The comment has been removed