ITS Standards

DC Kelley · Last edited by DC Kelley on Wed Mar 08, 2006 8:42 am; edited 2 times in total

This thread is of interest only to those who want a comprehensive help system for new users of the tool. With time we may be able to document the stds themselves in much the same way (would not that be cool for programmers using the messages), but that is a year away.

As we develop both an on-line user manual and other support tools, I am now playing with two "help" tools, HelpScribble and VBDocument and trying to combine the results of each.

The first, HelpScribble seems like a good tool to make t integrated user manual and screen for stewards and end users users and will provide Parts I and Parts II (a best practices section and a screen-by-screen detailed user manual section for controls). Building these is part of the current Phase II improvements program that FHWA has funded.

Part III, a programmer summary of how to remotely run Mini-Edit (needed by other 3rd party tool effort) will be done by VBDocument and we will likely only expose the routines other programmers need to know about (there are nearly 1000 methods and functions right now, most of which are private to the tool). I have posted the initial *.CHM file that this tool was able to produce in a few hours of work - there are almost no useful comments as yet because we need to reformat ALL the VB and C code comment for this tool to properly add them. Adding all that meta-data is an unfunded task so it will have to wait until we complete the current Phase II improvements, but here is what the tool dumps out at present. Note that it matches the format of Microsoft libs documentation quite well.

Aside: We might take a standard such as ATIS and document its messages the same way some day along with matching message memory strucs. This seems to me to be a very good thing to help development teams reduce the messages to things thy directly know how to build. Somebody propose that to the JPO and lets do it Wink

DC Kelley · Posted: Mon Mar 06, 2006 12:43 pm Post subject: DrExplain, another help tool

Here is yet another varient for the common "screen shots become help manuals" style of documentation. This comes from a brand new tool called Dr.Explain (see www.DrExplain.com ) that automates the capture of the screen and then hooking up the controls that need to be explained.

I like the overall style of this and particularly like that I can get control groups (such as all the buttons used in selection what table to view) into a small bit map. I do not like that the tool seems to be rather stand-alone at this point and I can not add further text and pop-ups, and links and cross-ref data to the pages.

I have attached the CHM file it produces from the three simple screen shots so other can see the overall style. I have not decided if we should use it, it will depend on what happens when I try and import its work to other tools. I might use this to document the ITIS picker tool, it looks like a good fit there.

DC Kelley · Posted: Mon Mar 06, 2006 7:59 pm Post subject:

Here are the two HTML sets for DrExplain and VBDoc (the two major components we want to use). I can not get these merged with HelpScribble (the various import-export styles do not match up) and am now playing with HelpStudio as an alternative (too damn complex!) Looks like we may loose pop-ups in process, but that may be a function of how Msoft is moving. All these are $100 tools except the last one which is $500.

Another interesting plus for the HelpStudio tool is that Msoft just annouced they have bundled a lite version of it with the next release of dot NET making it a large market share winner in all this. Oh well, another day of testing ahead.....

DC Kelley · Posted: Wed Mar 08, 2006 8:49 am Post subject:

The path from DrExplain (I keep hearing the schlock rock tune "Dr feel good" in my head with that title) to HelpStudio seems very workable. That seems to be our winner regarding what tools to use, adding VBdoc latter. Below is a semi-mature DrEx output (we need to use the HTML pages) that I will import and further develop as our text case.

This set of documents deals with the ITIS picker (see the thread at http://serv4.itsware.net/bb/viewtopic.php?t=63 to download that tool) because it is so simple I could document its use in an afternoon.

Site Admin · Posted: Tue Jul 18, 2006 10:53 am Post subject:

This thread is overcome by events at this point.

The final help system is now part of the tool and also available on line.

You can find the help system at:
http://www.itsware.net/miniedit/help/help.htm