How do you find the WinFX Documentation

I spent some time talking with some folks from the LH sdk team today about the quality of documentation for WinFX.  What do you think?  How do you find the quality of the docs in the LH SDK? What areas are good, what areas need help?  If you had $100 where would you spend it?  Conceptual documentation, API reference, HowTos?


Love to hear your feedback.

Comments (11)

  1. Tom Kirby-Green says:

    I think conceptual is real important. You definately need to convey the "Tao of WinFX", if you catch my drift.

  2. The comments section at the bottom is a good idea but I think it is just scratching the surface. If there was a good way to incorporate blog entries, we could all gain a lot of value. Imagine a "link to a related blog entry" input box that allowed me to enter the url of an entry that dealt with this particular namespace of class member. Add in a little google style ranking and over time the quality of the doc gets better just through use of community. This would get especially helpful in error situations. People working with X function often get an error and start reading the doc to figure out what happened. They then jump into google groups and search with the error message and comb thru huge threads hoping to find a person who experienced the problem and figured out what they were doing wrong. If you can cut out the trip to google and the human thread parsing and by way of community usage and ranking find a way to link directly to (or suck into the doc itself) the blog entry or newsgroup post that has a proper solution…well; that would be pretty snazzy 🙂

  3. Kevin Daly says:

    HowTos maybe, or just generally examples of pretty much everything.

    The LH SDK docs are pretty similar in style and content to the existing .NET Framework documentation (although there are improvements for sure),and a big problem with the latter as I see it is that a lot of features are described pretty much in terms of themselves – i.e. they’re documented wonderfully so long as you already know what they are, how you use them and why you would want to (although the last item on that list is sometimes made tantalisingly clear, just so the developer knows that it is an incredibly useful feature that would be just what they need to solve their problem if only they had the faintest idea what to do with it).

  4. Jason Nadal says:

    I was disappointed there’s only one page (so far) on speech technology. Frankly, I think in this community most people would lean more towards conceptual documentation, where in the general developer community, there’s a large demand for the "howto."

  5. Blair Stephenson says:

    I’ve found it OK. The samples are too small and have no real world aspect to them.

    Why not create a pet store example app using Avalon, Indigo using SQL server?

    Or even better, create an open source project on GotDotNet and have some of your talented developers working on this?

    I guess much like the ASP.Net Forums by Rob.

    Sorry I’ve gone of the topic of documentation :), but I still think a project or sample like this would be of great benefit to not only the community but also to Microsoft and is a great compliment to the documentation.

  6. Adam Hill says:

    I would spend:

    $30 – Conceptual

    $20 – How To’s

    $20 – API Ref

    $20 – Client Example Apps

    $10 – Web Example Apps

    I am looking for 3D, Video, Animation focus. That is going to be one of the big change areas for me in Longhorn.

  7. good brief code examples are the only real thing – code speaks louder than words. (sounds like something don box would say)

    you’d do well to always separate out code examples and syntax highlight them with colour.

    onto the money question. i think i’d put it in a mutual fund attached to a margin loan because of the tax advantages and the greater leverage. 🙂

  8. Adam Kinney says:

    Other than filling holes where methods/properties/constructors are without descriptions I would add to the "How Do I?"s.

    When they have highlighted code and contextual remarks around the code they are pretty helpful. I ask for more because right now it seems either an object doesn’t have one or it uses the same example as another object because they are similiar.

    Conceptual (at least as mentioned above) doesn’t in my opinion fit so much into documentation as it does into a good book or article. So I would probably send Adam Hill’s $30 off to MS Press or MSDN Mag or something like that.

  9. Adam Hill says:

    While I could spend my $30 on MS Press, I would like at least $5 from people like Brad and Co. to give us under the sheets commentary on whats going on.

    Its not quite the level of ‘conceptual’ that most people think of. Unless you are a compiler writer or trying to optimize some bottleneck, COM Interop is a good example of what I am thinking about.

  10. Kevin Daly says:

    I’d just like to add a point about samples and the Real World: while it is handy for samples to have some similarity to a scenario that might actually be one in which the feature in question would realistically be used, I would also argue that the code should be the simplest necessary to provide the necessary illustration. Otherwise it just leads to confusion as to what is essential to the correct operation of the feature being demonstrated, and what is just part of the demo scenario (this is actually one of the problems with the previously mentioned situation where the same samples are used for multiple related entries).

  11. Carl Thomas says:

    I think you’ve done well in the conceptuals, although a lot of it is scattered around and gets confusing with all the back and forth links to little paragraphs. Better organization neede here. There are big gaps in the API references and related HowTos… that I’d sure like somebody to take a crack at. Also some major gaps in the samples. I know – work in progress. Keep up the good work. I’m having fun trying to figure out some of the stuff not covered in the docs.