> 1. Do people use the online MSDN documentation for the WDK or the
documentation that comes with the WDK?
When I do development on our drivers (I am not a full time driver
developer) the WDK help is my first source of information.
(Then comes this newsgroup and then other web resources, including MSDN.
When I don’t do development, I still read this newsgroup.)
- Are people aware of the WIKI feature of the MSDN documentation?
> Do you use it?
No, I was not aware of it. And I will probably never use it.
- A local search/browse is usually faster than using the online MSDN, so
the first source of information for me is the locally installed WDK
documentation.
- And when I found an article in the WDK documentation, why should I
look up the very same article in the online version, only to check if
someone has added a comment?
I think WIKIs are very valuable (we are very successfully using one at
work), but as SO stated before, it is not reasonable to use it if you
have to use yet-another-system. Too many sources of information don’t help.
- What do people think of “document explorer” the tool that presents the
WDK documentation? Is it better or worse than previous versions? Do you
use the search from it?
a) It is a good tool, but there are some areas that “need improvement”
(explanation follows).
b) It is better than the October 2005 MSDN library browser. 
c) Are you kidding? “I use it” is very much of an understatement! About
30% of the time I spend in the WDK documentation I am searching and
looking for cross-references.
Document Explorer issues:
- What is really a pain is that the contents window does not update
(e.g. upon request by a button-click) to show me where in the TOC a
searched-and-found topic is located.
- When I search for an article, usually the Search function works well
and I find relevant information quickly.
- Then I ususally spend several minutes guessing where in the TOC the
found page is located to see into which contect the matter belongs and
what other relevant material is in the “vicinity” of the article.
(This is “lost lifetime”, and therefore very annoying!)
-
I would be happy if I could integrate some older MSDN library content
into the WDK help system. We need to use some older version of the SDK,
but nevertheless I would like to have one access to the information
(and not have to search in three different systems).
-
Document Explorer takes over the IE display settings (Text size,
etc.). And settings changed (like text size) are not stored and kept
from one Document Explorer Session to the next.
4: As the topic was mentioned before: I would like to (a) store my own
annotations to the documentation, and (b) if possible share them with my
co-workers and/or the community.
(For example collecting links and searches for specific topics to
provided a “guided tour” for someone who co-develops or maintains my
code would be great. Or linking it to specific modules and/or products.)
- Would you like to see samples in the documentation? Should they be
like:
a. Visual studio’s complete programs:
b. Platform SDK’s samples functions:
c. Platform SDK’s code fragments:
Yes, code samples are essential. It is important to see something used
in its environment and also the “surrounding” code.
Personally, I think a., b. and c. should all be used, but for different
purposes / contexts:
a) In the “real world application section”, a full sample shows how a
complete sample works. Of course the sample also lives in the file
system, where it is compiled, etc. But for a first glance it would be
nice to have the file available “on a click” from the documentation.
b) Fully explained and annotated code samples help to understand the
“side issues” - Format b. is helpful for providing more context.
c) Excerpts should be used to highlight or explain one specific issue.
I’m sure there are enough Microsoft folks to relay the discussion back to
right people, and those of us who were at the sessions have the emails to
send stuff to encourage reading this.
Not many things translate faster into “return value” than good
documentation and support. Obviously Microsoft does know this -
otherwise they would not have gone to such great lengths already to
improve the available WDKs and Help resources (Thanks!!).
But of course there’s still room for improvement.
-H
