What you are describing is a good book. Not MSDN Library.
On May 13, 9:48 am, "Igor Tandetnik" <itandet...@mvps.org> wrote:
Specifically what details do you feel are missing from MSDN
documentation? Do you have any particular problem?
I have to agree with the OP's comment. MSDN docs are abysmal for
anyone trying to learn how/when to use a particular interface (I guess
they're vaguely OK as a reference if you are already familiar w/ the
interface), and they are split apart into so many different webpages
that it's extremely cumbersome to use them. IObjectWithSite (http://
msdn2.microsoft.com/en-us/library/ms693765.aspx) is discussed in
abstract terms without giving any concrete examples of why/when you
might want to use such a thing, and the web page took me 23 seconds to
finish downloading. I clicked on the SetSite link and it took 22
seconds to download. They are also next-to-impossible to print out
properly.
Microsoft seems to have architected the MSDN docs to be viewable
online only, and autogenerated from some database without any attempt
to make them understandable or useful to the novice programmer.
A halfway decent documentation on this interface would have put the
method documentation in the same page as the overall interface
description (there are few enough methods and they are each short
enough to include inline) and would have explained a few sentences
like, "For instance, in an application where there is a main window,
blah blah blah is an example of a possible site and a yeah yeah yeah
is an object which can be contained in the site. Blah blah blah and
yeah yeah yeah should be in-process objects to avoid the cost of
marshalling."
The root webpages for interfaces (e.g.
http://msdn2.microsoft.com/en-us/library/ms693372.aspx
for OLE/data transfer) should give a list of these interfaces and a
brief description of each.
These pages aren't too bad (http://msdn2.microsoft.com/en-us/library/
ms692707.aspx and http://msdn2.microsoft.com/en-us/library/ms693383.aspx)
but again, they're split apart into so many different web pages, with
each new link taking 15-30 seconds to download, that it becomes very
cumbersome.
A really good documentation would be a white paper in .PDF format that
includes all of the above along with some basic examples of use and
some common pitfalls to avoid. I'm an electrical engineer and for
semiconductor IC's it is the norm for component datasheets to be in
PDF form with a minimum number of different documents; in many cases a
single 8-10 page datasheet is sufficient, and sometimes there is a 2nd
PDF file which is an "application note" so they split up the
specification & suggested use information into 2 documents. Processor
ICs tend to be a bit more complicated with maybe a half-dozen
documents taking 1000-2000 pages total, but it is still possible to
print them out and read them all without having to navigate a maze of
webpage links. The same thing goes for MATLAB documentation; you can
search and browse the Web if you want, but you can also print out PDF
files for each general area of use (basic programming techniques,
graphics, signal processing, etc.) and after you read a PDF file you
have a decent general understanding of what's going on, and where to
look if you have further specific questions.
Not true for Microsoft's MSDN. With all the billions of dollars
floating around that company, I just don't see why they can't spend
0.001% of their money on good documentation for their standard
interfaces so people can learn to use them without having to thrash
around in the dark.