This article will introduce Dynamic Help in Visual Studio .NET. An overview of the Dynamic Help Window is presented. The components, mechanisms and navigation controls comprising dynamic help functionality are also shown. Finally, the systematic, logical thought process involved in creating content targeting the dynamic help window of the Visual Studio .NET IDE will be emphasized. This article will be the briefest of the series and focuses on the logical process of creating help content. If you want to further investigate the practical aspects of this topic, excellent content is available on the Microsoft MSDN Online Library at http://msdn.microsoft.com/library.
This series is designed around two central premises: first, this series teaches foundational concepts of Enterprise Templates; second, this series demonstrates how to create Enterprise Templates using various types of available Visual Studio .NET Projects. This article series will benefit two types of audiences the best: individuals curious about Enterprise Templates (with little knowledge or experience developing Enterprise Templates), and individuals familiar with the fundamental concepts of Enterprise Templates (but seeking a more application-oriented, tools-development approach to constructing Enterprise Templates).
The .NET Architect Enterprise Template Series will help you build the following projects:
Enterprise Template Editor Add-In
Enterprise Template Editor Web Service
Enterprise Template Editor Windows Service
Enterprise Template Editor Web Control
Enterprise Template Editor Windows Control
Enterprise Template Editor Framework
Requirements
Visual Studio.NET Enterprise Developer, or Enterprise Architect Edition
Section 1: Introduction Section 2: Dynamic Help Overview Section 3: Dynamic Help Components Section 4: Dynamic Help Development Process Summary About The Author
Section 1: Introduction
One of the most critical components of any application is the help file collection. These files describe the functionality of your application, provide contextually relevant information about performing tasks within your application, and provide a way to structure tutorials for your end users. The systematic, logical discipline of applying structure to the volumes of informational artifacts generated during the development process is not currently emphasized in help file generation. Because of the excellent tools available to create help files, the logical thought process often gets overlooked or shoved aside in the name of deadlines or laziness. Rest assured that shortcuts up front during the help file creation process will translate into an inferior product - no matter what market position your company holds. Properly thinking through the structure and content of your help files shows attention to detail, pride in your application or product, and can result in a more loyal user base. So, before you crank up your favorite HTML editor, be sure you take the time to run through the Help File Creation Process, and as always be sure to have fun!
The .NET Architect Enterprise Template Series comprises the following articles:
Article 4: Enterprise Template Dynamic Help <-- YOU ARE HERE
Article 5: Enterprise Template Exercise
Article 6: Enterprise Template Editor Add-In
Article 7: Enterprise Template Editor Web Service
Article 8: Enterprise Template Editor Windows Service
Article 9: Enterprise Template Editor Web Control
Article 10: Enterprise Template Editor Windows Control
Article 11: Enterprise Template Editor Framework
Article 12: Enterprise Template Developer Notes
Section 2: Dynamic Help Overview
The Visual Studio .NET IDE Dynamic Help Window provides real-time, contextually relevant information about a variety of elements and topics during the software construction process. This information is displayed within the "Dynamic Help Window", accessible by selecting the " Dynamic Help" option from the "Help" menu. You may also access the full contents of the Visual Studio .NET Help Files via the Dynamic Help Window as well. To access the entire help file collection, click the "Contents", "Index" and "Search" buttons of the Dynamic Help Window respectively. The Dynamic Help Window is designed to be extensible, as are most items in Visual Studio .NET, and will display your own custom-created help content as well.
There are three main components to the default Dynamic Help Window: the Contents Button, the Index Button, and the Search button. Each of these buttons launch the full Visual Studio .NET Help File Collection in the appropriate mode. For example, if you click the "Index" button, the Dynamic Help Window will attempt to locate and open the Visual Studio .NET Help Collection in the Index View mode. Clicking a link inside the default Dynamic Help Window will also locate and open the selected topic in the full-screen mode of the Visual Studio .NET Help Collection. Think of the Dynamic Help Window as a series of quick links to guide the user where to find more specific information about their selected topic.
You can create customized help content for the Visual Studio.NET Dynamic Help Window. Creating custom dynamic help involves the following steps:
Step 01: The Gathering Step
Step 02: The Grouping Step
Step 03: The Linking Step
Step 04: The Layout Step
Step 05: The Markup Step
Step 06: The Compilation Step
Step 07: The Deployment Step
Step 08: The Integration Step
Step 09: The Testing Step
Section 3: Dynamic Help Components
The following diagram demonstrates the default component parts to the Visual Studio .NET Dynamic Help Window.
Section 4: Dynamic Help Development Process
STEP 01: THE GATHERING STEP Step 1 in creating custom help content for the Dynamic Help Window in the Visual Studio .NET IDE is to gather the information you need. This includes the text, images, layout concept, code samples, and any other information artifacts relevant to the topic you want to explain. This step merely forces you to evaluate all information sources, choose the information to incorporate, and begin the process of making order out of informational chaos.
STEP 02: THE GROUPING STEP Step 2 in creating custom help content for the Dynamic Help Window in the Visual Studio .NET IDE is grouping together information that meets common grouping criteria. You should begin thinking about creating categories of information in a hierarchical manner. At this step, you assign each informational artifact to one or more of your informational groupings. For example, you choose to create an informational category named "Web Services", with a sub-category named "C#". You add your tutorial on C# Web Services to the "Web Services->C#" category. To see an example of STEP 02, simply open the Visual Studio .NET Help Collection and expand any branch of the help tree. You will see a tree-like structure of organized informational units. After building your information hierarchy, the next step is to link the informational artifacts together in a logical, consistent manner that guides the user around your content. As a result of skipping this step, and going straight to STEP 05: The Markup Step, many good intentioned help projects end up to be an illlogical, unmanageable, unintelligible mess of disconnected information. The feeling of being lost in informational overload is exactly what the end user is trying to avoid. Be kind to your end-users and resist the temptation to immediately begin marking up your informational sources with HTML.
STEP 03: THE LINKING STEP Step 3 in creating custom help content for the Dynamic Help Window in the Visual Studio .NET IDE is cross-linking your informational artifacts in a manner that facilitates information navigation, understanding, and retrieval. When linking your informational artifacts, always provide visual, contextual clues to help guide the user around your content. If the user gets lost, be kind and make it easy for the user to return to the places they were browsing before they got lost. Avoid the temptation to hyperlink every link to every other link. Following this approach is guaranteed to confuse and frustrate your end-user. Remember, the user views help files to learn something new, to improve upon a skill already mastered, or lookup the syntax or structure of some informational entity. As the designer of the help content, your job is to ensure your users can find what they need regardless if they are trying to learn something new, improve upon a skill already mastered, or looking up the language syntax or structure of an informational element. Choose your linking scheme carefully. There is nothing worse than working with a help file with great organizational structure but a poor linking structure.
STEP 04: THE LAYOUT STEP Step 4 in creating custom help content for the Dynamic Help Window in the Visual Studio .NET IDE is selecting the layout of your pages. At this step, questions are asked such as, "Where do the images go?", "Where do the navigation features go?", and "How do the users search for items?". This step is mainly concerned with defining the layout and structure of the page itself. For example, will there be frames used? Will there be tables, floating frames, or span tags used? This step is a precursor to the actual HTML markup. If you have not already done so, you should read some good books on magazine and page layout techniques. You should learn some common layout rules such as "The Rule of Thirds", or the "Rule of Symmetry" or "The Rule of Balance." If these terms are foreign to you, that is ok. By reading books on informational design, human-computer interaction and page layout techniques, you will be well-prepared to apply your knowledge of these areas to the pages to be part of your help files. However, that which is organized and linked can still be unusable to the end user. If the visual layout of the pages are not easily readable and traceable by the user's eyes, the end user will interpret the layout as a sloppy mess of visual mistakes. If you are saying to yourself, "There is a lot to learn about help file creation" you are correct. However, with a little effort you will find the process fun, enjoyable and worth your time.
STEP 05: THE MARKUP STEP Step 5 in creating custom help content for the Dynamic Help Window in the Visual Studio .NET IDE is taking each page of content and marking it up using HTML. This is the culmination of steps 1-4 above. You will take your organizational hierarchy and apply the HTML markup to each page. The specific HTML tags used depend upon which browsers you are targeting. The most common types of browsers are Microsoft Internet Explorer, Netscape Navigator, and the Opera Browser. When choosing the set of HTML tags to use be careful. Each browser may interpret and render the tag in a different way. While there is an official Internet Engineering Task Force (IETF) document describing the recommended implementation of HTML, there is no guarantee that a specific vendor has not added HTML tags to their browser implementation of HTML. For example, Microsoft Internet Explorer adds the "<FIELDSET>" and "<LEGEND>" tags to simulate HTML Group Box functionality. Regardless of the browser and platform your help files will support, marking up your HTML can be the most time consuming step in the process. Today's HTML tools like RoboHelp(tm) can ease the process of marking up your pages using HTML and are worth the cost if you produce large volumes of help.
STEP 06: THE COMPILATION STEP Step 6 in creating custom help content for the Dynamic Help Window in the Visual Studio .NET IDE is compressing your HTML files to make distribution easier. After finishing step 5 above, your collection of help files is apt to be quite large. Compressing these files into one distributable collection becomes easy with compression. Your HTML files are compressed into .CHM files, which stands for "Compressed HTML." Once your HTML files are compressed and converted into the .CHM format, they can be easily transported between computers or devices that support the .CHM format. Users can now simply double-click the .CHM help file to launch your help file. While you can certainly distribute uncompressed help files, it is not recommended and is discouraged.
STEP 07: THE DEPLOYMENT STEP Step 7 in creating custom help content for the Dynamic Help Window in the Visual Studio .NET IDE is deploying the .CHM Help File to your end users. Common distribution mechanisms include network file shares, loading the .CHM files onto the user's local machine, and peer-file sharing networks. The help files you deploy in this step are stand-alone help files. There is no real integration with your application as yet. However, you will integrate your help files with your application in step 8.
STEP 08: THE INTEGRATION STEP Step 8 in creating custom help content for the Dynamic Help Window in the Visual Studio .NET IDE is integrating your help files with your application. In the step above, you distributed your help files as stand-alone files. This allows your end users to search the help file without opening your application. Most users will have questions as they navigate your application. To accommodate these requests, the "F1" key is provided. Pressing the "F1" key loads your help file and navigates to a specific, contextually relevant point in your help file. In your source code, identifiers are assigned to each user interface element in your application. These identifers are used to locate the proper help topic in your help files. The last step is to test all context-sensitive help options in your application.
STEP 09: THE TESTING STEP Step 9 in creating custom help content for the Dynamic Help Window in the Visual Studio .NET IDE is testing all context-sensitive links in your application. The goal is to verify each help link navigates to the proper place in your help files. While this step might seem trivial to most programmers, it is very important for the end user experience to maintain consistency. If even one link malfunctions, the inconsistent state of your help files will confuse and frustrate the end user. Make sure you exercise due diligence and thoroughly test every link before releasing your help collection to the end user.
Summary
This article introduced Dynamic Help in Visual Studio .NET. An overview of the Dynamic Help Window was presented. The components, mechanisms and navigation controls comprising dynamic help functionality are also shown. Finally, the systematic, logical thought process involved in creating content targeting the dynamic help window of the Visual Studio .NET IDE was covered.
The Visual Studio .NET IDE Dynamic Help Window provides real-time, contextually relevant information about a variety of elements and topics during the software construction process. This information is displayed within the "Dynamic Help Window", accessible by selecting the " Dynamic Help" option from the "Help" menu. Clicking a link inside the default Dynamic Help Window will also locate and open the selected topic in the full-screen mode of the Visual Studio .NET Help Collection. Think of the Dynamic Help Window as a series of quick links to guide the user where to find more specific information about their selected topic.
Creating custom dynamic help involves the following steps:
Step 01: The Gathering Step
Step 02: The Grouping Step
Step 03: The Linking Step
Step 04: The Layout Step
Step 05: The Markup Step
Step 06: The Compilation Step
Step 07: The Deployment Step
Step 08: The Integration Step
Step 09: The Testing Step
Step 1 in creating custom help content for the Dynamic Help Window in the Visual Studio .NET IDE is to gather the information you need.
Step 2 in creating custom help content for the Dynamic Help Window in the Visual Studio .NET IDE is grouping together information that meets common grouping criteria.
Step 3 in creating custom help content for the Dynamic Help Window in the Visual Studio .NET IDE is cross-linking your informational artifacts in a manner that facilitates information navigation, understanding, and retrieval.
Step 4 in creating custom help content for the Dynamic Help Window in the Visual Studio .NET IDE is selecting the layout of your pages.
Step 5 in creating custom help content for the Dynamic Help Window in the Visual Studio .NET IDE is taking each page of content and marking it up using HTML.
Step 6 in creating custom help content for the Dynamic Help Window in the Visual Studio .NET IDE is compressing your HTML files to make distribution easier.
Step 7 in creating custom help content for the Dynamic Help Window in the Visual Studio .NET IDE is deploying the .CHM Help File to your end users.
Step 8 in creating custom help content for the Dynamic Help Window in the Visual Studio .NET IDE is integrating your help files with your application.
Step 9 in creating custom help content for the Dynamic Help Window in the Visual Studio .NET IDE is testing all context-sensitive links in your application.
About the Author
Brian is the CEO/President of "Brandari", a Colorado-based technology company specializing in .NET/C# software development for a variety of industries. Brandari is currently accepting new clients. Reach Brian at: vbanswerguy@adelphia.net. Please visit Brandari's Web site at: http://www.brandari.net for more information about the company.
In this article, Joseph Poozhikunnel examines the importance of the three X's -- namely XML, XML Schema, and XSLT -- in a service oriented architecture (SOA). He then defines the design considerations that need to be adopted when designing a system based on SOA and examines the pitfalls that can arise if they're not followed. [Read This Article][Top]
In this article, Joseph Poozhikunnel defines an Enterprise Service Bus (ESB) that can be created to support any Service Oriented Architecture (SOA) adopted by an organization. The type of ESB required could vary as there is no "one size fits all", therefore the article examines a few of the mechanisms available that could be adopted to implement an ESB. [Read This Article][Top]
In the seconmd part of his series on building an end user defined data model, Peter Scheffler gets into the actual meat of the model and discusses real-world implementation details and the actual table layouts. [Read This Article][Top]
In the first article in this series, Peter Scheffler introduces the concept of a rules-based database engine that allows clients to make changes to their database structure without breaking the applications that access the database. [Read This Article][Top]
The basic premise of a Service Oriented Architecture (SOA) system is to decouple applications from each other in order to make them autonomous. In this article, Joseph Poozhikunnel presents a simple SOA framework that can be used as a starting point for a system that addresses your specific business needs. [Read This Article][Top]
A well rounded versioning and deployment strategy considers several overlapping and interdependent .NET Framework concepts. In this article, Michele Leroux Bustamante will take you through a ten step program that reviews these core concepts, their relationship, and provides guidance for successful application deployments for the .NET Framework. [Read This Article][Top]
Adnan Masood continues his discussion of Microsoft SQL Server Analysis
services and Microsoft SQL Server Reporting services. In this part, he
discusses the steps that go into building more advanced reports. [Read This Article][Top]
Adnan Masood discusses Microsoft's comprehensive integrated business
intelligence, data mining, analysis and reporting solution: Microsoft SQL
Server Analysis services and Microsoft SQL Server Reporting services. [Read This Article][Top]
Chip Irek examines the architectural issues and component design issues of building a .NET application in a service-oriented architecture. [Read This Article][Top]
The importance of reuse can't be overstated, especially in light of the
degree to which we go out of our way to avoid it, but implementing a reuse strategy means creating high-quality low-cost applications that just might save your job. [Read This Article][Top]
Mailing List Want to receive email when the next article is published? Just Click Here to sign up.
