.NET Buzz Forum - K-Links: Small Pieces, Loosely Joined

This post originated from an RSS feed registered with .NET Buzz by Korby Parnell.

Original Post: K-Links: Small Pieces, Loosely Joined
Feed Title: Korby Parnell
Feed URL: /msdnerror.htm?aspxerrorpath=/korbyp/Rss.aspx
Feed Description: Copyright 2003 Korby Parnell Fri, 01 Aug 2003 10:03:48 GMT ChrisAn's BlogX korbyp@microsoft.com korbyp@microsoft.com Alex Lowe Joins Microsoft http://blogs.gotdotnet.com/korbyp/permalink.aspx/536bb108-6a66-4dc6-8847-69f4d799bb55 http://blogs.gotdotnet.com/korbyp/permalink.aspx/536bb108-6a66-4dc6-8847-69f4d799bb55 Fri, 01 Aug 2003 10:03:48 GMT From ASP.NET MVP to Microsoft .NET Evangelist. Success is the domain of good guys. Welcome aboard Alex. I look forward to meeting you in person. Thanks to ScottW for posting the big announcement. Este mensaje se proporciona "como está" sin garantías de ninguna clase, y no otorga ningún derecho.

Latest .NET Buzz Posts

Latest .NET Buzz Posts by Korby Parnell
Latest Posts From Korby Parnell

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.


	Web Artima.com