다음을 통해 공유

K-Links: Small Pieces, Loosely Joined

  • 아티클

K-Links are dynamically generated hrefs in HTML Help
2.x help topics. Currently, my division (Visual Studio + the .NET
Frameworks) uses them in a limited capacity. I would like to change
that.

For Visual Studio .NET
2002 (and 2003), I implemented a k-link table in the help topic for the 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.

In this case, my New Project dialog box help topic
is the caller. 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):

<MSHelp:ktable keywords =
"vs_NewProjectDialog_ProjectType"
indexMoniker = "!DefaultAssociativeIndex" filterString = "" disambiguator =
"table" topicHeader = "Topic" locHeader = "Location"/>

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
satellite--must include
"vs_NewProjectDialog_ProjectType" as an A-keyword.

<MSHelp:Keyword Index="A"
Term="vs_NewProjectDialog_ProjectType"/>

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
runtime.

 

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.
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).

Pros

  • Noise
    Reduction
    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.

  • No Broken
    Links
    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.

  • No Link Checker Needed
    Currently,
    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.

Cons

  • Less Writer Control
    Popular
    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].
  • Duplicate Links Possible
    If the
    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
    perform?)
  • Performance
    K-links have a minor
    impact on the render time of a topic.
    Solution: faster computers
    :-).
  • Empty See Also
    Node
    If no
    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
    node?
    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 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
übernehmen.