As the developers of IssueNet, we are often asked how we use the product internally. There are two answers to that question, the operational answer and the practical day-to-day answer. Operationally we use IssueNet for many core functions: software defect tracking, external customer support, internal IT help desk, CRM, and miscellaneous issue tracking. But what people are usually asking is: in the practical course of our days, how do we interface with the system most? It varies some from department to department, but our favorite interface is the Microsoft Outlook integration.

Let's face it, these days, we all spend a great deal of time in our email, so working directly in that environment makes us more productive. How you might ask?

• IssueNet integration to Microsoft Outlook is achieved via an unobtrusive toolbar
• Quick access to creating all types of issues and viewing existing issues and tasks
• Special functionality to easily create issues from mail messages and append messages to existing issues.

The ability to quickly create issues from email messages is extremely important, because invariably, most issues are first reported through email. The quick ability to turn those random emails into trackable, actionable issues in the issue management system means less issues fall through the cracks.

We love the integration because it is easy to use on a daily basis, but that ease of use also serves a very important role in user acceptance during a new deployment. Making issue tracking available via the user's email application dramatically increases uptake for new deployments. Email clients are typically open all day so elminating the need to launch a separate application or browser tightly integrates IssueNet into the daily routine. All this adds up to an easy, low-overhead way to manage issues.

Additional Information on Outlook Integration

• Short Video Demonstration (Elsitech.com How-To Videos Section - Video titled: "Workspace Integration to Microsoft Outlook")
• Detailed Feature-by-Feature Documentation of Outlook Integration (help.elsitech.com)

Elsinore made the decision to switch from Compiled HTML Help edited with RoboHelp to a wiki-based help system using Screwturn Wiki.  The following is a look into the decision making process that ultimately lead to replacing RoboHelp with a Wiki.

Issues with RoboHelp

In general, we were very frustrated with RoboHelp.  After using it for many years and through several versions of our product, we had assembled a critical mass of grievances.

• Lack of flexibility around updates which were not tied to releases
• Rigidness of source code control and upgrade pains
• Web Help required rebuild of the entire project to generate .htm files, which took 10-15 minutes and required additional files to be checked into source control and then picked up by the Product build system.  This often resulted in internal builds not having updated Help files installed. 
• Updates simply took too much time, effort, and planning.  When a new help resource is available, we want to make it available quickly and effortlessly. 

Advantages of Wiki for Product Help

• Updates made in real-time
• Ability to easily link to other sources of rich content (tech tips, how-to videos, blog entries, developer labs articles, etc.)
• No need for product to "phone home" for help updates
• Source code available so customers can deploy on own network
• Extremely easy for staff to update
• Freedom from RoboHelp compatibility issues
• Free to near-free

Disadvantages of Wiki for Product Help

• Difficult to compile for a printed manual
• Difficult to implement context-sensitive help
• Conversion of existing data from RoboHelp into new format takes time
• Traditional version control approaches must be rethought

The idea of converting a large existing documentation base from RoboHelp to wiki format can be daunting.  In the end we found that it would be easier to manually convert from RoboHelp to wiki than to convert from our older RoboHelp version to newer versions.  The manual conversion also dovetailed nicely with a comprehensive review and update of the documentation.  There are also some conversion tools out there such as the RoboHelp2Wiki tool, which may be useful in the right situations.

We went with Screwturn Wiki over the other available variants for the following reasons:

• ASP.NET
• File-based
• Easy Xcopy deployment, with no need to configure outside dependencies

Summary

In the end, the ease of use and extensive flexibility of the wiki format made this an easy decision.  Our priority was to update our help on a real-time basis with a minimum of frustration for our internal staff, and those goals were best achieved by converting our help from RoboHelp to a wiki. 

We are pleased to announce that our IssueNet product help is now available online at help.elsitech.com. The system is hosted with wiki technology provided by ScrewTurn Wiki, and will completely replace the compiled HTML help (.chm) within IssueNet products with the next release of the product. Changing from compiled HTML help to online help edited via wiki technology offers several key advantages:

• Changes to help are available to all users instantaneously without the need for software updates or software "phoning home"
• Ease of editing is much greater for Elsinore staff, which leads to fresher, more relevant documentation for our users. We like when things are easy too!
• Help that is rich with content. Using online, wiki-based help allows us to quickly add instructional video tutorials, tech tips, and developer labs content directly into the relevant sections of the help.

Changing a process that has been in place for many years is always tough. Since many of our customers are software companies facing these decisions as well, we've written up a short summary of our decision making process to switch from compiled HTML help, edited with RoboHelp, to wiki-based help edited with Screwturn. Check the blog next week for that entry!

An IssueNet system is very accessible. Options such as a full .NET API and a SOAP API provide limitless integration options for those with the time and expertise. However, a quick-and-dirty option is often preferable. With the absence of an industry standard .NET scripting platform and the general inflexibility of a command line interface, another option is needed. This is where the IssueNet tasks for MSBuild come in. Don't let the name fool you-- MSBuild is as useful for common scripting as it is for building projects.

MSBuild tasks are compiled in .NET dlls, then configured in XML project files, and can be executed from the command line. Standard tasks include Touch, MakeDir, and FindUnderPath. 3rd parties have implemented task libraries with functionality ranging from file access to XML manipulation. IssueNet tasks include the following:

• ExecuteIssueNetQuery - Execute a stored query in an IssueNet system. The results will populate an MSBuild item.
• CreateIssueNetObjects - Creates one or more objects in an IssueNet system. The objects are passed in as MSBuild items.
• UpdateIssueNetObjects - Updates one or more objects in an IssueNet system. The objects are passed in as MSBuild items.
• LinkIssueNetObjects - Links together two objects in an IssueNet system.
• TransitionIssueNetTasks - Transitions one or more tasks in an IssueNet system. The objects are passed in as MSBuild items.

These tasks accomplish 90% of what our customers are doing with the full API, and getting up and running is a bit simpler.  The following MSBuild project file executes a query in order to transition tasks:

   1:  <Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">

   2:      <UsingTask TaskName="Elsinore.Engine.MSBuild.Tasks.ExecuteIssueNetQuery" AssemblyFile="Elsinore.MSBuild.dll" />

   3:      <UsingTask TaskName="Elsinore.Engine.MSBuild.Tasks.TransitionIssueNetTasks" AssemblyFile="Elsinore.MSBuild.dll" />

   4:   

   5:      <Target>

   6:          <ExecuteIssueNetQuery ConnectionName="$(IssueNetConnectionName)" UserID="$(IssueNetUserID)" Password="$(IssueNetPassword)" QueryName="MyTaskQuery">

   7:              <Output TaskParameter="Results" ItemName="QueryResults" />

   8:          </ExecuteIssueNetQuery>

   9:   

  10:          <TransitionIssueNetTasks ConnectionName="$(IssueNetConnectionName)" UserID="$(IssueNetUserID)" Password="$(IssueNetPassword)" Objects="@(QueryResults)" TransitionName="Start" />

  11:      </Target>

  12:  </Project>

The following occurs in the execution of this file:

• Line 1 is the standard outer Project tag for an MSBuild project file.
• Lines 2 and 3 declare that we are using two tasks from the IssueNet library, ExecuteIssueNetQuery and TransitionIssueNetTasks.
• Line 5 delimits the beginning of our target. This file only has one target. However, MSBuild allows multiple targets to be defined and selectively evaluated.
• Line 6 executes a query named "MyTaskQuery" and Line 7 stores the results in an item "QueryResults".
• Line 10 executes a transition "Start" on each task in "QueryResults".

We've even released a MSBuild HTTP Gateway for those adventurous enough to expose the functionality over the web.  If you have any questions, feel free to post them in the comments.