Creating a help system or user manual in Dr.Explain

Hello. Probably, any developer who asks what you most dislike during the development process will answer: “writing documentation” or mention it at the very beginning of the list of problems. There is really nothing interesting in documenting, but, nevertheless, the user guide, as I wrote in my first post on Habré , is an important component of any professional product. Poorly compiled documentation will not only be an obstacle to attracting new customers, but is also a big minus to the product and developer image.


')
At the same time, a program with a good help system will almost certainly be bought. Despite the widespread belief that no one reads the user's manual, life shows the opposite. If a user has purchased a multifunctional program with which he has never worked before, then the user's help will become his reference book, which he will turn to in order to quickly master the program’s capabilities and find answers to questions arising during the operation of the program. Therefore, clear, consistent and concise user reference is always a big plus to the positive image of the product and its potential for profit.

I myself sometimes do help-files and know firsthand that creating a help system takes time and is painstaking and tedious work, especially documenting the interface. However, a couple of months ago I discovered a tool that speeds up this process considerably. This is a program Dr.Explain from the Samara-based Indigo Byte Systems. I liked the thoughtful interface and the ability to document the software interface in semi-automatic mode.

Dr.Explain vs. Help and Manual

So, Dr.Explain allows you to create help files in CHM format for delivery along with the application, help systems in HTML for posting on the product site, as well as user manuals in RTF and in PDF with tables of contents and links. The help system is generated in different formats from a single source, which allows you to quickly update the documentation when new software versions are released. In this regard, Dr.Explain is no different from Help and Manual , which I have been using for a long time.

The interface consists of two areas. The first is a navigation bar with a tree structure of the project content. And the second is a page editor.



The tree defines the entire structure of the help file, including the headers of folders and pages. The page editor consists of standard tools for writing and formatting text, and there are tools for inserting hyperlinks, images, tables, and variables. All this is in the Help and Manual, but the toolbar in Dr.Explain is arranged, in my opinion, more thoughtfully.

Compare:



Figure 1. Dr.Explain toolbar



Figure 2. Toolbar Help and Manual

The main feature of Dr.Explain is the automation of the most time-consuming documentation process - the creation of user interface annotations . Yes, you understood me correctly. You no longer need to take screenshots yourself, draw notes and arrows, insert all this stuff into the project manually - the program will take a snapshot of any part of the interface of your choice, analyze and find (itself!) All significant elements (buttons, controls, lists) , insert a snapshot into the help project and automatically arrange arrows and explanatory notes to the images. The user needs only to enter a brief explanation for each callout and that's it.

In addition, more detailed explanations can be added to the callouts. For all callouts, the program will automatically generate a nice-looking plate that will be placed below the screenshot of the callouts and may include all these detailed explanations.

Such semi-automatic documentation of the interface greatly speeds up and facilitates the creation of a help system, since the developer need only add his descriptions to the callouts. In Help and Manual, I can do all this, too, though I will have to do it manually. Usually I take pictures of windows in Snagit, process the edges of the picture, add a shadow, draw arrows. And to document the elements of the window, I manually create a tablet, cut pictures of buttons and controls, process their edges and insert them into the project, and then write descriptions of each callouts. It takes a lot of time and effort.

Something else…

Dr.Explain has other useful features that, unfortunately, are not in the Help and Manual. For example, there is a convenient mode of viewing the project - with one click on the corresponding button you can quickly see how the help will look in CHM or HTML format after compilation. The preview opens right in the editor window. Believe, it is very convenient. However, there is no PDF preview - this is a minus. In Help and Manual, to see how help looks, you need to constantly compile the project.



The program also has the ability to integrate context-sensitive help directly into the application (F1), navigation tree management, a set of design templates, support for CSS, the ability to quickly update the documentation when a new version of the program is released by replacing illustrations, but preserving callouts, annotations, descriptions; Search and index function in online help without programming (PHP, ASP) or server-side databases.

Summary

Here, perhaps, are all the main points that I wanted to talk about here. I wanted to write a short review of Dr.Explain two months ago when I first saw the program, but then I put it off indefinitely. And recently I again prepared the user's help in Help and Manual and once again made sure that it is still more convenient to document the interface in Dr.Explain .