Software learnability increased with Context-Sensitive Help

The last years I have been especially focused on UI usability and ergonomy. Actually since its inception, six years ago, the tool NDepend had a constant feedback: awesome features that come with a steep learning curve. Whatever the efforts put on UI usability, some features are de-facto more obvious than others: A Graph is more intuitive than a Dependency Structure Matrix or than a Treemap:

After a long process of collecting feedbacks, we came to the conclusion that what we needed was a sort of Context-Sensitive Help. From Wikipedia on Context-Sensitive Help (CSH):

Context-Sensitive Help is a kind of help that is obtained from a specific point in the state of the software, providing help for the situation that is associated with that state. Context-sensitive help, as opposed to general online help or online manuals, doesn’t need to be accessible for reading as a whole. Each topic is supposed to describe extensively one state, situation, or feature of the software.

Concretely CSH is implemented through tooltips. However, typical tooltip was not an option for us mostly because a tooltip is located near to the mouse pointer. In our situation, locating the tooltip near to the mouse pointer makes the tooltip overlaps important visual data .And also, using a typical tooltip would force to often relocate the tooltip. So our CSH tooltip has a unique location: it is located just below the panel currently in use. Now, whatever the artifact hovered by the mouse in an NDepend panel, the user gets a plain-english explanation about what is pointed. If no artifact is hovered, the CSH tooltip automatically fades away to release screen real estate. However the fading speed is sufficiently slow to let the user catches back easily with the mouse the CSH toolip if more investigations are needed.

In the screenshot below the CSH tooltip explains why the pointed Dependency Matrix Cell is blue and what does the number on the cell mean:

In the screenshot above there are actually two tooltips: one below the panel, the Context-Sensitive Help, and one on the right panel side, the Info view. Typically the Help targets beginner users (it explains why the cell is blue) while the Info targets experienced users (it provides data description: 19 members of the namespace XXX are used by 20 methods of the namespace YYY).

We underline the fact that these tooltips are only shown when the user hovers a panel with the mouse. Anyway, because such large tooltips consume screen real estate, there are situations when the user will prefer to hide one or both of them. Hence tooltips can be hidden/shown with a single mouse click. Once hidden, two icons in the bottom left corner will remind the user that Context-Sensitive Help and Info are available if needed.

The CSH tooltip itself becomes a pointer to more documentation on the most interesting usage of the feature. For example an important reason of being of Dependency Structure Matrix is its awesome capability to make obvious, patterns that wouldn’t be obvious if the structure would be displayed with a graph or a diagram. Layered structured code is one of such pattern amongst others as shown in the sub-tooltip below. And if this is not enough, the sub-tooltip represents a pointer to the online documentation that goes into even more details.

We’ve just released this new CSH and we are looking forward user feedbacks. Hopefully this will make the tool more learnable for beginners and experimented users will certainly learn something from it.

This entry was posted in Uncategorized. Bookmark the permalink. Follow any comments here with the RSS feed for this post.
  • Patrick Smacchia

    Tooltips are built just-in-time depending on available info on the context.

  • Cara Levy

    Hi :-)
    I am actually a tech writer. One of my developers called me over to show me NDepends CSH.
    After I got up off the floor, I ran a few searches and found your blog.
    You did this all by hard-coding  it into tooltips? If so, that must have been a huge job! or did you find a way of pulling it in from a source file.
    Very, very impressive!

  • thomas

    Great feature !
    Looking forward to check it asap.


  • Charles Strahan

    Excellent news, Patrick. I found the CSH very useful in the pre-release/trial version – can’t wait to update to the real deal.