< Back     Next >

portfolio: Program

A programmer's core skill is a natural ability to recognize problems and apply logical and efficient state-of-the-industry solutions appropriate to the situation.


User-centered design

IBM® DB2® DataJoiner was a product that required complex configuration, involving various network communication and database connection properties. User testing revealed an overwhelming need for us to simplify the process.

expand/collapse details

Rather than change the already improved configuration documentation, I chose to offer users a configuration wizard to automate the tasks.



The wizard was created using a combination of SGML, C, SQL, and standard network and database APIs.

// Create the user mapping for access to 'master' strcpy(sqlStmt,"CREATE USER MAPPING FROM USER "); strcat(sqlStmt,"TO SERVER djxsgdsq AUTHID \""); strcat(sqlStmt,user); strcat(sqlStmt,"\" PASSWORD \""); strcat(sqlStmt,using); strcat(sqlStmt,"\""); EXEC SQL EXECUTE IMMEDIATE :hSqlStmt; rc = sqlca.sqlcode; if (rc < 0) { setSQLError(&sqlca); goto exit; }

collapse details



Innovation

It's 1996. Popup windows and hypertext graphic links are rarely seen in OS/2 help, unlike WinHelp where writers use them extensively. Like HTML, OS/2 help code is a tagging language with presentation and content intermixed. Once a help author starts writing, it's nontrivial to change the presentation behavior if the user feedback suggests to do so.

expand/collapse details

Familiar with the benefits of simple mail merging, it seemed to me that separating the presentation code from the content data was the logical solution. They could then be developed separately and simultaneously. I used perl since XML and XSL weren't yet available.

The content is written as text strings and assigned to field variables in a file.

. . . $obj = "obj.bmp"; $objbut = "objbut.bmp"; $ObjTit = ":hp2.Objects in This Folder:ehp2."; $ObjStr = ":p.To get more information on a particular\n" . "field, button, or other object in the folder,\n" . "click on an area in the graphic."; . . .

The presentation code is contained in the transform script, which pulls in the text from the data file and generates the composite help code. The resulting code is compiled as normal to produce the OS/2 help file.

. . . print "\n:font facename='Helv' size='12x8'."; print "\n:hp6.$Title${Line}:ehp6."; print "\n:p.:artwork name='${graphdir}$obj' runin.$ObjTit"; if ($review) { print "\n:font facename=default size=0x0."; print "\n:hp8.[${ResID+4}]:ehp8."; print "\n:font facename='Helv' size='12x8'."; } print "\n$ObjStr\n:artwork name='${graphdir}$ObjBMP' align=center."; . . .

An added benefit to the system was that it let me deliver various versions of the help with little effort: a graphic intensive US-only version, an international version without graphics, and a version that displayed resource IDs for reviewers, such as the one in the following figure.


collapse details



Day-to-day application

Mundane repetitive tasks are a nuisance to productivity and a hindrance to quality, as they increase potential for human error.

expand/collapse details

Early in my career as a writer, I recognized the value of the Perl language, which was originally designed to parse and manipulate text files. It's a perfect companion. In addition, the script capability of today's operating systems provide wonderful tools to handle those error-prone tasks.

In the time it takes to document a routine manual procedure, it can be just as easily scripted and automated. For example, the following Windows® batch file is used to build, post-process, and index JavaHelp.

        if not exist initcalled call varinit.bat
        
        cd %HELP%
        if exist DocUser rd /s /Q DocUser
        md DocUser
        attrib -r *.$*
        del *.$* *.bak
        REXX IIDDHTM "mtkhelp.idd" /S:. /DCL:IBMIDDOC /V:props.val
        call postproc.bat
        for /f "tokens=2 delims= " %%i in ('date /t') do ^
          perl -pi.bak -e "s/\d\d\/\d\d\/\d\d/%%i/;" readme.txt
        
        if exist JavaHelpSearch rd /s /Q JavaHelpSearch
        call %JHHOME%\javahelp\bin\jhindexer.bat ^
          -verbose DocUser Docs Msgs
        if %WHICHBUILD%==s (
          jar cvf %MTKRUNDIR%\help.jar help
          wzunzip -d -ybc docs.zip .
        )

collapse details

< Back     Next >