2.x help topics. Currently, my division (Visual Studio + the .NET
Frameworks) uses them in a limited capacity. I would like to change
2002 (and 2003), I implemented a k-link table in the help topic for the href="http://msdn.microsoft.com/library/en-us/vsintro7/html/vxurfNewProjectDialog.asp">New
Project dialog box, mainly because the dialog box itself failed to
provide the type of granular context sensitivity that I thought users would
expect (yup, my feature team was insensitive to my pleas for improved context
sensitivity). For example, when a developer selects a C++ project item in the
New Project dialog box and clicks Help, they would presumably expect
to see a help topic on the C++ project. Instead, they are confronted
with my boring and somewhat irrelevant UI Reference topic for the
New Project dialog box. To improve the user documentation experience, I planted
a K-Link table in the middle of the topic–a table which doesn’t appear in
the online version of the topic–and sent a special keyword to the
language-specific project writers. When my k-link enabled topic is
rendered, the HTML Help engine queries the current collection (MSDN
Combined Collection) for topics with this special keyword. A link to
topics containing such keywords automatically appears at the specified location
in the topic. Effectively, a non-Microsoft Fortran project topic can
appear in the table that didn’t even ship in the same box as my New Project
dialog box topic.
is the caller. face=Arial>I like to think of it as Mother Earth. Here’s
what its ktable looks like (an XML data island in the HTML code of which
the topic consists):
indexMoniker = “!DefaultAssociativeIndex” filterString = “” disambiguator =
“table” topicHeader = “Topic” locHeader = “Location”/>
size=2>The only thing that you (as a Fortran
project vendor perhaps) have to worry about is the keyword. To push a link
into my ktable, your sender topic–which I like to think of as a
“vs_NewProjectDialog_ProjectType face=Arial>” as an A-keyword.
size=2>Easy, huh? Of course, the sender
topic must reside in an HTML Help 2.x HXS file that has been properly registered
into the same collection as my topic’s hxs (MSDN Combined Collection). But once
it’s there, a link to your topic appears in my topic dynamically at
size=2>K-links can be formatted as tables, lists,
bulleted lists, numbered lists, or symbol-delimited lists. In my opinion,
all VS.NET and .NET topics should be klink-enabled in the See Also list.
class=321083419-14082003> class=321083419-14082003>Here are some arguments
for and against the blanket implementation of k-links across the Visual Studio
.NET and .NET Frameworks documentation (or any similar HTML Help 2.x collection
for that matter).
size=2>Visual Studio .NET ships in several SKUs: Academic, standalone
languages, Professional, Enterprise Developer, and Ent. Architect. In a
SKU-ified world, hxs and sub-hxs portability and granularity are increasingly
important. K-Links are an easy way to ensure that the help provided an
up-level customer is not a “lowest common denominator” user experience.
For example, when an Enterprise customer clicks Help in the New Project
Dialog box, the help topic should contain a link to Enterprise Template
Project documentation. On the other hand, when a Visual Basic .NET user clicks
help in the New Project dialog box, she should not see any links to the Enterprise
Template project docs. She cannot create ETP projects and shouldn’t have
help for them.
If a topic gets removed from an hxs or its hxs is not
registered into the user’s current collection, a link to the topic
does not appear.
class=321083419-14082003>No Link Checker Needed
if writerA changes the title of a topic to which which writerB links,
writerB’s topic has a bug. WriterB’s link no longer matches the
title of WriterA’s topic. If all See Alsos are k-links, link topic titles
will never get unsynchronized.
class=321083419-14082003>Less Writer Control
topics such as “Solution Explorer” in VS.NET could be burdened by way too many
See Also links. Additionally, writers would not be able to determine
the order of hrefs in their topics, which is sometimes necessary to the
discoverability of intimately related topics.
Possible Solution: Change
HTML Help 2.x code to limit # of topics (this may already be possible?).
and… [see next bullet].
class=321083419-14082003>Duplicate Links Possible
writer of SourceTopic1 adds a link to SatelliteTopicA and the author of
SatelliteTopicA adds the k-link kwd to their topic, SourceTopic1 will have two
links to SatelliteTopicA.
Possible Solution: HTML Help 2.x feature change
to check for duplicate links (a task which it might already
K-links have a minor
impact on the render time of a topic.
Solution: faster computers
class=321083419-14082003>Empty See Also
k-link topics are available in the current collection, no See Also topics
would appear. In this case, what do we do with the See Also
Solution: change to HTML Help 2.x code to hide empty klink containers
such as the “See Also” header.
By the way, the K in
K-Links does not, as popular myth might have you believe, derive from
my first name. For more information about how to create HTML Help 2.x hxs’
and collections, see href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hwmscExtendingNETHelp.asp">Visual
Studio .NET Help Integration Kit. You must have either VS.NET 2002 or 2003
on your computer and you must install the appropriate VSHIK package to
access the help topics.
Well, back to the VSS
and SCS docs…. Meine kleine
disclaimer: Microsoft kann für die Richtigkeit
und Vollständigkeit der Inhalte in dieser Newsgroup keine Haftung