Tim Sullivan, one of the fabulous
software development engineers on my team, bares all in this review of proposed changes
to the Visual Studio help system.
Folks, when Microsoft says it intends to be more transparent in
the design and development of software, Microsoft means it. Tim gets you
as close to the feature development action as you can get without attracting some
really sticky bugs. Here are few quotes from Tim's
a bit of commentary from your's truly:
"Help and Community are getting a lot
of attention in Whidbey."
-- Show me the money!
"Unfortunately, due to the sheer number
of help topics in MSDN and a few scheduling and organizational issues, I can pretty
much guarantee that a number of help topics will still be sub-par when we ship Whidbey."
-- Self-supporting communities of like-minded developers will continue to be an invaluable
resource into the foreseeable future. We're raging against the machine to pump
out code examples but those .NET Framework fools (Brad
Abrams, Don Box, et al) are
freakin' prolific. No rest for the weary though since companies, including Microsoft,
continue to unveil new .NET languages. Seriously, I love to troll our international
product feedback reports for fish like this (not an actual quote but similar to real
ones), "Help would
be *perfect* if the
existing topic for the System.Math.Cos function was
available in Swedish and included J# and COBOL .NET examples, especially ones related
to accounting." Wouldn't it though?
make sure to use the 'send feedback' links whenever you find an MSDN topic that's
not to your liking; those bits of feedback are all read by actual people and they
result in bug entries that someone will be responsible for fixing."
-- SEND FEEDBACK! I'm one of those actual people and your actual feedback actually
helps me help you better. It's a virtuous cycle. You can even mention
that I sent you, if you want. ;-)
also have the option of going online for F1. This will have 2 beneficial effects:
First, you'll get the very newest help topics."
-- Personally, I disagree with this feature and encourage you to stick to the offline,
on-disk help topics. In my opinion, it's a mistake to point users to two versions
of a help topic without giving them more information and context. In particular,
users should be able to determine which topic is more up to date, the online
version or the offline version. As this F1 feature is currently implemented,
I don't think there's a way to do so.
do I... -- This
is an entirely new view into the help system. It's a hierarchical organization of
common tasks a developer is likely to encounter. Each developer segment (VB, C#, Web,
etc.) will have its own hierarchy containing roughly 200-400 tasks. Each task will
contain carefully reviewed editorial text along with sample
code that can be
copied and pasted into the VS editor. The documentation teams have been collecting
user feedback to help determine which tasks to include in the hierarchies. If you
have ideas for tasks you'd like to see in a How do I... page, let me know and I'll
pass them along to the right people. You can think of How Do I... as a hand-picked,
carefully designed subset of the Table of Contents."
-- Sweet. I could have used this when I was learning about XPath.
of Community content:
Going online to access MSDN content
has its benefits, but the biggest win in searching online is really the ability to
access living content. If you look at some of the fantastic work that Community-based
web sites like .Net247, CodeProject, ASP.Net,
and others have done, it's clear that static content published to the web can never
be as rich as content that is provided by members of the developer community. "
-- You said it, brother. The more community, the merrier.
get me wrong, MSDN's API reference is obviously important. But if you open that
content up to be annotated and extended by people in the community, then it becomes
a much more powerful resource."
-- Timmaaayyy, NOW you're talkin'.
code snippet looks very comprehensive, but .Net 247's page provides so much more variety,
and it's directly linked to a forum where I can ask questions about the code and interact
with the code authors or other forum members. The experience at the Community-based
site is much richer because the content is far more dynamic and because I
can interact instead of just reading."
-- Community Community Community Community !
how does this apply to VS? In Whidbey we have partnered with a number of Community
sites that will allow MS to aggregate and search their content
from the VS client. " -- That's right,
we're baking community into the Visual Studio IDE.
In response to reader comments Tim writes:
(paraphrasing) How will all this community stuff show up in the IDE?
Newsgroups, forums, and web sites that are part of the CodeWise program will come
back as part of Community search results. Annotations will be an intrinsic part of
the online versions of the topics. Blogs and RSS feeds are on the radar, but we don't
have a good story for them yet. If you have ideas on how you'd like to see them integrated,
let me know."
-- Hm. Allow me to qualify... Annotations may be an intrinsic part of the online
versions of topics. As much as I, like all developers, love the MSDN
Annotations feature, it's not a done deal yet. They're still testing the
Blogs and RSS feeds? Heck Tim, don’t hesitate. Don’t
waffle. Don’t vacillate. Visual Studio should support both the creation and consumption
of RSS feeds. A native newsreader should be plugged into the IDE and you should
be able to publish stuff (like build errors) to an RSS feed using automation.
posting is provided "AS IS" with no warranties, and confers no rights.