From the Doc Side : Infinity

Screencasts aka Video Tutorials in the Help Mix

Justin Baden — Tue, 05 Aug 2008 22:11:00 GMT

Recently, Denise Kadilak wrapped up a series of blog posts that explored the cool help functionality we’re building into our next generation applications. To top it off, she just posted an excellent screencast on BBLabs that guides you through the nuts and bolts. If you’re not familiar with screencasts, they’re basically guided UI videos with audio narration.

A few members of the doc team, including Lindsey Robbins, Nikki Tremann and Denise have been exploring the possibilities of producing screencasts to publish along with our other help content. And as you can see from Denise’s example, the exploration was a success. Moving forward, we intend to use screencasts where it makes sense but we won’t overuse them. They’re effective at communicating in a visual way that'll benefit users trying to complete more complex processes… but they’re overkill for more intuitive tasks. We've also decided to call our screencasts "video tutorials," which clearly communicates the purpose to users who may be unfamiliar with the screencast terminology.

In the very near future we hope to have additional video tutorials to share… I know Nikki has a BBNC video tutorial in the works that covers processing individual sign-up requests in RE. Hopefully, we can publish that soon so you can take a look and let us know what you think. In the meantime, drop a comment and let us know what processes you'd like to see made into video tutorials.

BTW – We’re using Adobe Captivate to create our video tutorials.

UPDATE :: Nikki's BBNC video tutorial is posted here. You'll have to log in to view it.

Blackbaud's Next Generation of Help - Part 3

Denise Kadilak — Tue, 01 Jul 2008 12:15:00 GMT

Now that we have looked at what Blackbaud enterprise help offers our end-users and their clients - Part 1 and Part 2 - this week we will take a look at the technology driving the help system. We will also talk about how this technology serves to make our search functionality cutting edge.

Technology

As I mentioned in Part 1, the server-based help system is designed to be installed on a Web server along with the Blackbaud Enterprise application itself, which is deployed as a ClickOnce rich-client application. In the help system, HTML topics are wrapped in Microsoft ASP.NET version 2.0 code, which interacts with two Web services that call the code from the application. This technology enables us to display context-sensitive information and dynamically generate links to topics for all the functions a user has rights to on a given page of the application.

Implementation

All “pluggable” features in the application support linking with help topics: tasks, search lists, reports, data forms, pages. Pages in the application support multiple help topics: root page level, page level actions, page sections, and page section actions. Each of these items is associated with a “HelpKey” property in the code. By default, HelpKeys are specific HTML filenames of topics within the system. But end-users can modify HelpKeys (no coding necessary) and include other file types that display in a browser (doc, pdf). They can also link to fully qualified URLs. See Part 2 of my series for more information about manipulating help keys in the system.

As a result, when a user accesses our help system from any given page, a GetPageMetaData Web service builds a list of links related to functions on the page to which a user has security access. The help content for the page (usually an overview) appears, along with a scrollable pane on the left side of the screen containing the dynamically generated links, allowing users easy access to all help associated with the selected help topic.

Search

Blackbaud’s help system depends on Microsoft Indexing Service, which extracts content from files and constructs an indexed catalog to facilitate the user’s search. The service is initialized and configured for Blackbaud Enterprise help on the Web server with an install utility that is part of the application.

The Search field is available from every topic in the help system (via the ASP.NET wrapper). When a user executes a search, an ASP.NET handler issues a query against the indexing service search catalog, which is configured to include all files in the application Help directory. Each time the service indexes the catalog, changes to existing files, as well as new files are included. So end users can add their own documents or topics to the Help directory, and these files are included in search results.

The results are returned and displayed in a dynamically generated html page.

Blackbaud's Next Generation of Help - Part 2

Denise Kadilak — Tue, 24 Jun 2008 12:52:00 GMT

In my last post about our next generation of help, I provided an end-user view of our new help system and mentioned in passing the customization functionality. In this post, we will take a more detailed look at the customization feature.

Customization

All help topics in the enterprise help system are fully customizable. As part of the user's work-flow, we recommend that users cut and paste all topics from the default Help directory to a Help/Custom directory so future updates do not overwrite topics they may have edited.

Via a single change to a web.config file, users can specify that all current HelpKeys point to files in the custom directory rather than the default Help directory. Users can then open an HTML topic, enter their changes, and save the edited topic. The next time a user accesses this topic, the program calls the edited version. Users can also add new topics. All edited and added topics are fully integrated in the search and recognized by the application.

Tools built into the application make changing the help keys used for a given page, screen, or feature easy. Using a design mode tool, accessed from the application's Tools menu, users can access the properties screen from which help keys are assigned.

When a user clicks the ellipses in the HelpKey field, a topic browser appears, listing all available help topics.

The user simply selects the new help key he wants used in the selected area in the program and clicks OK.

Additionally, users can provide a URL or the name of one of their own files as a HelpKey. For example, a user can place a pdf version of his organization’s in-house policy and procedures document in the Help directory, then specify the pdf as a HelpKey for a specific page instead of the default topic. The next time a user accesses help from that page, the pdf document displays in the main content pane.

Next Week's Blog

Next week we will examine the technology driving the new Blackbaud enterprise help system and take a closer look at the search functionality.

Blackbaud's Next Generation of Help - Part 1

Denise Kadilak — Fri, 13 Jun 2008 12:59:00 GMT

Early in 2005, Blackbaud Inc. started work on an enterprise version of our constituent management software product. We targeted the software to high-end users interested in a powerful and customizable product, and of course, we wanted the help system to be equally powerful and customizable. From this desire was born the Blackbaud Enterprise help system. Currently employed in four different applications, the enterprise help system provides on-demand, context-sensitive help, dynamically generated links, and is fully customizable. In the coming weeks, I plan to specifically address each feature. In this my first help post, I provide an overview of how the system works on the client side.

Access Help

The server-based based help system installs on the client's Web server along with the application and can be accessed in a number of ways. From any page or screen in the application, to access context-sensitive help information, a user can:

Click the Help button
Press F1

In addition, from the help page, the Contents button opens a table of contents and the Index button accesses a detailed help index. A Search field is also available on every help page, but we will talk more about this functionality in a later post.

Procedures
When users access a procedure page in help, the page appears displaying a brief explanation of the functionality and an expandable procedure link, keeping the page neat and tight - no scrolling.

Users click the link to expand the procedure.

Reference Information
Screens in the application usually include a number of fields and options. Because we do not want to bog down our procedures with a laundry list of field explanations, we arrange this information in a separate table, easily accessed from a link included in the procedure. These reference topics are also presented as context-sensitive topics when help is called from a given screen in the program.

Conceptual Information
The concept pages in the help system include information explaining the concept governing a function.

Dynamically Generated Links

In addition to displaying the called help information, the help system dynamically generates links to other areas in the help related to tasks, actions, sections, and other items included on the page from which the help is called. For example, a constituent page is composed of a series of tabs and includes a list of tasks you can execute from the page. If a user calls up help from a constituent page, the help page displays a detailed explanation of the page, and the links displayed on the left side of the page take the user to additional help information specific to each tab and task.

Next Week's Blog

As I mentioned in the introduction, users can customize the help file to better meet their specific needs. Next week, we will take a detailed look at this customization feature.