How do you like your samples???


style="FONT-SIZE: 10pt; FONT-FAMILY: Arial">We have heard very clearly that you
folks want more samples, but where would you like us to invest. style="mso-spacerun: yes">  IMHO there are really three kinds of
samples we can invest in: "urn:schemas-microsoft-com:office:office" />


style="FONT-SIZE: 10pt; FONT-FAMILY: Arial"> 



  1. style="MARGIN: 0in 0in 0pt; mso-list: l0 level1 lfo1; tab-stops: list .5in"> style="FONT-SIZE: 10pt; FONT-FAMILY: Arial">SDK level samples. style="mso-spacerun: yes">  These are typically more complete
    samples that ship in the SDK.

  2. style="MARGIN: 0in 0in 0pt; mso-list: l0 level1 lfo1; tab-stops: list .5in"> style="FONT-SIZE: 10pt; FONT-FAMILY: Arial">Quick Starts. Like this: href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpqstart/html/_net_framework_quickstart_samples.asp">http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpqstart/html/_net_framework_quickstart_samples.asp

  3. style="MARGIN: 0in 0in 0pt; mso-list: l0 level1 lfo1; tab-stops: list .5in"> style="FONT-SIZE: 10pt; FONT-FAMILY: Arial">Sample code in line in the
    reference docs such as this one: href="http://msdn.microsoft.com/library/en-us/cpref/html/frlrfSystemObjectClassGetHashCodeTopic.asp">http://msdn.microsoft.com/library/en-us/cpref/html/frlrfSystemObjectClassGetHashCodeTopic.asp

  4. style="MARGIN: 0in 0in 0pt; mso-list: l0 level1 lfo1; tab-stops: list .5in"> style="FONT-SIZE: 10pt; FONT-FAMILY: Arial">Other?

style="FONT-SIZE: 10pt; FONT-FAMILY: Arial"> 


style="FONT-SIZE: 10pt; FONT-FAMILY: Arial">So, if I gave you $100 to invest,
where would you spend that money between these 4 choices?


style="FONT-SIZE: 10pt; FONT-FAMILY: Arial"> 


style="FONT-SIZE: 10pt; FONT-FAMILY: Arial">Thanks for your
input!

Comments (33)

  1. My money is on the sample code in the reference docs. Since it’s integrated into the Visual Studio help, that’s the first place I go for information. And on that topic, any sample code that generates text output should show what the output is!! Don’t make me compile sample code just to see what the expected result is. That’s why I go to the documentation in the first place – because I expect it to be quicker than experimentation. Other than that one issue, I have to say that the reference documentation is great.

  2. Don McNamara says:

    $100 on number 3 please.

    I use the help files almost every day — I can’t remember the last time I looked at a quick start or SDK sample.

    (I’m not sure if you are counting the application blocks in this list, but they are well worth it. If you are counting app blocks, I would split my money 50-50.)

  3. Sergio Pereira says:

    I’m 100% with Jesse. Just ran into this frustration of examples in the reference that don’t tell the output.

  4. Keith Hill says:

    I tend to like to see the shortest possible fragment of code possible to illustrate a concept (or how to use an API). My favorite Windows API book of all time is "Windows API BIble" because for every single Windows API there was a usually short snippet of code that showed how you might use it. Having this in the online docs is best place for this because that is where I go for info about a particular type member. I would put about $70 there.

    I’d put about $20 in the SDK samples because I think you also need fully, loadable samples that demonstrates concepts that span a single type member. I don’t know that I would put more than $10 in the quick start samples. I have rarely used them.

  5. Sample code in line with reference documentation would be my vote. The others are appealing as well, but the majority of my $100 would go towards the sampe code.

  6. 1. $50
    3. $50

    The help files are kind of the first line that you hit, so you need to get a quick overview and possibly best practices/common pit falls etc.

    Beyond this stage, I personally prefer much more involved, ‘real-life’ apps that help you understand the details by seeing the code.

    Kind of theory (1) and practice (3) 🙂

  7. Jeff Julian says:

    I would go with code samples and a nice MSDN article with an "as-close-to" real world example in the text.

  8. Roy Osherove says:

    50$ on No.3 and I would add another type of help – FAQ lists – Kinda like thre quickstarts – but for advanced short answer-questions

  9. Paul says:

    $75,- on #3 and the rest on starterpacks and other complete implementations (eg petshop)

  10. Robert Cannon says:

    Definitely inline with the reference. That is where I spend most of my time. Also, consider something like http://www.dontnet247.com where there would be a link in the reference that would take me to a live page on MSDN that shows any articles related to that class.

  11. Todd Breyman says:

    $10 on #1
    $90 on #3.

    I only use the higher level examples when I am working with several methods with related contracts. Most of the time, I want specific examples of how to use the specific method I am looking at. When I go to the help documentation, I expect to see a simple usage example.

    How about this …
    – For classes with methods with very specific usage contracts (e.g. the ADO.Net classes), provide a SIMPLE example that walks through the most common use case for the class as a whole.
    – For methods, provide brief inline code examples that illustrate the use of the method along with links to other related methods.

  12. Your 100 and my own 100 on #3

  13. All on #3 for me. Code samples are indispensible. SDK samples and quick starts are neat to peruse, but usually too construed to be useful as building blocks.

    Two other suggestions for some possible improvements:

    1. *hyperlink* the keywords, types, and namespaces in the code samples, making it easier to dig into a sample and really understand it. Color-coding in VS.NET style would also be handy.

    2. Better documentation and linking for various types of string patterns. When I want to use regular expressions or format numbers or dates, I’m constantly fumbling around in the docs to find an actual table of symbols, escape codes, and meanings to construct the pattern. If a method requires a patterned argument, the word "pattern" in the docs should at least be linked to a quick reference for constructing the string.

  14. Dmitriy Zaslavskiy says:

    2. $50
    3. $50

  15. $80 on Number 3. Samples in the help is really important.. Help is the first place that you go when have a problem, or want to know something.
    $10 on Number 1&2

    A question I have is where does this fit with all of the other examples etc that are coming out of places like the MSDN articles, PAG (Perscriptive Architecture Group) etc.. These avenues are also good reference points for examples as well.

  16. Marco Russo says:

    1. $20
    3. $80

  17. Corrado Cavalli says:

    3. $100

  18. RichB says:

    Why not just ship the BVTs you test with? ROTOR is a pretty good source for samples because of the BVTs.

  19. Brad Abrams says:

    I got some emails, I wanted to include here for future reference… I am getting lots of folks on the product team to read this and I want them to have easy access to all the comments.
    —————————————

    1. $30

    2. $20

    3. $50 – BUT, too many times I’ve seen developers literally CUT AND PASTE the MSDN code into Production stuff. I would add more disclaimers, etc….even COMMENTS WARNING THEM within the very code they are cutting and pasting…

  20. Brad Abrams says:

    More comments I got via email
    —————————————-

    had $100 to spend on samples….

    SDK level: $5 – I simply don’t have time to go through and look at it all. However, someday I’d like to out of curiosity. So I do think they should exist.

    Quick Starts: $10 – I’ve never really taken a good look at them, but it seems to be aimed at people getting started. So for me, not to important. But for people just starting out, they could be invaluable.

    Sample code in ref docs: $40 – Very important. Due to the fact the ref docs are built into VS.NET, it’s fast and easy to access them. Plus, if you’re learning some new part of the framework, examples in the docs are very helpful to pull information together and help you learn.

    “Article Type” samples: $45 – My favorite kind of samples. By “article type”, I mean the things you’d find written on community sites or MSDN dev centers. Reasons why they are IMHO the most important:

    – They generally start out with a narrative, explaining a higher level reason (why) something is done a certain way.

    – The body of the article is code, mixed with a narrative. This gets down the what (ex: a certain class) and the when (ex: “after opening the connection…”), with additional why (ex: “because caching keeps it in memory…”)

    – They generally contain links to more articles. In the beginning, there are links to get familiar with any knowledge the authors assumes you’ll have. At the end, there are links to explore more on your own.

    Sorry for the lengthy email, just wanted to give a sufficient explanation.

  21. $80 on #3, and $20 on petshop, patterns and best practices code, and other full-implementation samples – I guess this might be the SDK option #1 you are talking about, but I find the code in the SDK different than what I find in any best practices guide/implementation.

  22. Ole Thrane says:

    $50 on help samples

    $40 on "Article Type" samples

    $10 on best-practice app blocks.

  23. $80 inline in the help.
    $20 on application blocks. We use those.

  24. Rich says:

    Got to go with #3 – Ref Docs!

  25. Klaus Ruggaard Mebus says:

    #2 = $10
    #3 = $90

  26. John Tobler says:

    #3 = $50
    #2 = $40
    #1 = $10

  27. Darrel Miller says:

    $100 on #2. It is a shame more people have not looked at the quickstarts. They tend to be far more realistic examples than in the docs. I really dislike the foo, bar, MyClass and SomeType examples. Give me a customer, rectangle or fruit anyday!

  28. somerandomguy says:

    $70 on #3 and spread the rest of the wealth on the other samples. Aint nothing worst then finding a method that you think would work for you but not know how to implement correctly.

  29. Matthew Adams says:

    $80 on 3, $20 on Quickstarts.

    The quickstarts are really useful for new material, but the examples inline in the reference documentation are invaluable for day-to-day "oh yes, that’s how you do it" refreshers.

  30. Shital Shah says:

    SDK Samples – $15
    Quick starts – $25
    In-line samples – $35
    Reference apps (like IBuySpy) – $25

  31. Clint Heyer says:

    Inline samples: $50, Quick Start: $50.