CA2242408A1 - Computer-based documentation and instruction - Google Patents
Computer-based documentation and instruction Download PDFInfo
- Publication number
- CA2242408A1 CA2242408A1 CA002242408A CA2242408A CA2242408A1 CA 2242408 A1 CA2242408 A1 CA 2242408A1 CA 002242408 A CA002242408 A CA 002242408A CA 2242408 A CA2242408 A CA 2242408A CA 2242408 A1 CA2242408 A1 CA 2242408A1
- Authority
- CA
- Canada
- Prior art keywords
- source code
- user
- interactive
- computer
- interactive example
- Prior art date
- Legal status (The legal status is an assumption and is not a legal conclusion. Google has not performed a legal analysis and makes no representation as to the accuracy of the status listed.)
- Abandoned
Links
Classifications
-
- G—PHYSICS
- G06—COMPUTING; CALCULATING OR COUNTING
- G06F—ELECTRIC DIGITAL DATA PROCESSING
- G06F9/00—Arrangements for program control, e.g. control units
- G06F9/06—Arrangements for program control, e.g. control units using stored programs, i.e. using an internal store of processing equipment to receive or retain programs
- G06F9/44—Arrangements for executing specific programs
- G06F9/451—Execution arrangements for user interfaces
- G06F9/453—Help systems
Abstract
User instruction on a computer system involves performing an interactive example and providing, in synchronization with the interactive example, explanatory information corresponding to the example. The explanatory information presented explains what most recently occurred in the interactive example and is updated automatically to correspond with the current state of the interactive example.
Description
PATENT
ATTORNEY DOCKET NO: 07042/120001 COMPUTER-BASED DOCUMENTATION AND INSTRUCTION
Background This invention relates to computer-based documentation and instruction.
A typical computer system as shown in Fig. 1 includes a computer 11 having a central processing unit 12, an input/output unit 13 and a memory 14 containing 10 various programs used by the computer 11 such as an operating system 15 and one or more application programs 16. An end-user of the computer system communicates with the computer 11 by means of various input devices (keyboard 17, mouse 18) which transfer information to the 15 computer 11 via input/output unit 13. The computer 11 replies to this input data, among other ways, by providing responsive output to the end-user, for example, by displaying appropriate text and images on the screen of a display monitor 19.
The operating system 15 may include a graphical user interface ("GUI") by which the operating system and any applications it may be running (e.g., a word-processing program) can communicate with a user of the computer system. A commonly used GUI implementation 25 employs a desktop metaphor in which the screen of the monitor is regarded as a virtual desktop. The desktop is an essentially two-dimensional working template area supporting various graphical objects, including one or more display regions. As shown in Fig. 2, information 30 generated by application programs or the operating system can be displayed on the desktop 21 within display regions 23 (e.g., windows, dialog boxes, pop-up menus, pull-down menus, drop-down lists, icons). The user can interact with the operating system, and any applications it may be running, by manipulating the cursor 24 appropriately within the display regions and by entering information with the keyboard or other input device.
To use an application program effectively, a user 5 must know not only how to interact with the application itself, but depending on the nature of the application, the user also must possess a body of substantive knowledge relating to the subject matter to which the application pertains. For example, if the application is 10 a software development environment, the user must be familiar with computer programming concepts and programming languages to use the application effectively.
Most computer applications provide an online help / documentation facility which aids in the use of the 15 application. A typical online help system such as shown in Fig. 3A is accessed through a GUI in which screens of textual and graphical information are displayed to the user in a help window 30. The user can then read the screens of help text to get a better understanding of the 20 application and its various features.
The user invokes the help system with a key sequence (e.g., pressing the F1 key on the keyboard) or by clicking the mouse on an appropriate graphical icon or menu item. In response, the help system may display a 25 table of contents 31 listing the available help topics and subtopics which can be accessed and viewed by the user as desired. The user can browse through the table of contents 31 and click a help topic of interest to cause its corresponding body of information to be 30 displayed in a help window. In the help window 30 shown in Fig. 3A, the user has clicked the "Programming with Microsoft Word" topic 31 to cause the corresponding help screen 32 to be displayed in window 30 as shown in Fig.
3B.
-The "Programming with Microsoft Word" topic 31 shown in Fig. 3B includes several subtopics 33, each represented by a separate "link." When the user clicks the mouse on one of these links--for example, the "Error 5 Messages" link 34--the text for the corresponding help topic is displayed automatically in the help window 30, as shown in Fig. 3C. In this example, the "Error Messages'r topic 35 includes several links to further subtopics relating to specific types of error messages.
10 As shown in Fig. 3D, when the user clicks one of these links, for example, the "Out of memory (stack space)"
link 25, a new help window 36 is spawned to display the corresponding help information ("Freeing up memory") for the selected topic. The help information displayed in 15 window 36 includes yet another link 37 for another subtopic, "active window," which when clicked by the user causes corresponding help text to appear in a pop-up dialog box 38. Virtually any level of such nested help displays is possible. The quantity and types of display 20 regions (windows, dialog boxes, etc.) used to display help information is largely a matter of design choice based on the preferences of the help system developer.
A help system may provide "context-sensitive" help information, meaning that the help system automatically 25 displays help information specifically relevant to the application's current task, rather than simply displaying all available help topics and forcing the user to identify and call-up the appropriate help topic manually.
A context-sensitive help system decides which help 30 information to display based on factors such as the current state of the application (e.g., the particular function being invoked by the user) and the current cursor position.
The information provided by most online help 35 systems relates to the mechanics of using features of an application. In Fig. 4, for example, the text 42 corresponding to the chosen help topic 41, "Cancel printing," describes how to control the print feature provided by the application 40 (Microsoft Word).
A help system also may provide substantive information on how to make use of the application to achieve a desired goal. In Fig. 5A, for example, the online help system provides two types of substantive information: reference material 51 for the WordBasic 10 programming language and practical explanations 52 of how to use WordBasic to write useful programs. The reference material 51 includes textual annotations describing the syntax and meaning of various WordBasic statements, such as the A~A~7n statement, the help text for which is 15 shown in Fig. 5B. The practical explanations 52 can include static examples of program code which the user can study to gain a better understanding of the WordBasic programming language. Fig. 5C shows an example of program code that makes use of the GetCurValues WordBasic 20 statement.
Online help systems typically are "built" (i.e., processed into a form that facilitates run-time operation) by compiling several different help source files containing help information that has been composed 25 by technical writers. In general, these help source files are maintained as a separate body of information apart from the application to which the help system corresponds. Consequently, when the application developers change or update the functionality of the 30 application, the technical writers must make corresponding changes to the help source files to ensure that the online help system accurately describes the operation of the application.
Summary In one aspect, user instruction on a computer system involves performing an interactive example or instructional demonstration and providing, in 5 synchronization with the interactive example, explanatory information corresponding to the example. The explanatory information presented explains what most recently occurred in the interactive example and is updated automatically to correspond with the current 10 state of the interactive example. The explanatory information may be presented concurrently or simultaneously with output from the interactive example.
A user of the computer system is enabled to control the performance of the interactive example or the 15 presentation of explanatory information.
Presentation of the explanatory information can include displaying multiple windows on a screen of the computer system, the explanatory information being displayed in one window and the output from the interactive example being displayed in another window.
In response to a change in state of the interactive example, the explanatory information provided may be altered accordingly.
A user of the computer system also may be provided 25 with access to online reference materials relating to the interactive examples, the explanatory information, or both. The online reference materials may be accessed through links in the explanatory information. When a user selects a particular link, for example, by clicking 30 the link with a mouse cursor, corresponding reference information is presented to the user. The links in the explanatory information can be arranged in a logical hierarchy, each successive level in the hierarchy providing an increased degree of detail.
A user of the computer system also may be provided with access to source code associated with an interactive example. A fragment of source code associated with an interactive example may be displayed in an annotation 5 associated with the example. The annotation also may include a prose description of the interactive example's operation. Access to the source code can be provided by an editing utility, which can be launched when a user of the computer system selects a visually indicated jump (e.g., a short-cut arrow) within the annotation. The user then can view, copy or modify the source code fragment in the context of the source code for the entire interactive example. The user can experiment with an interactive example by iteratively modifying the 15 example's source code and then executing the modified example to see what happens.
An application for implementing concepts illustrated by the interactive examples may be provided to the user. The interactive examples provided by the 20 computer-based instructional system can represent a subset of the functionality provided by the application.
For example, the interactive examples may correspond to computer programming concepts. In that case, a software development environment may be provided to allow the user 25 to implement the programming concepts illustrated by the interactive examples.
The interactive examples and the corresponding annotations describing the interactive examples can be built from a unified body of source code. Markup 30 symbols, demarcating a portion of the source code to be used in building an interactive example and another portion of the source code to be used in building an annotation describing the interactive example, can be included in the unified body of source code. The portion 35 of the source code to be used in building an interactive example can overlap the portion of the source code to be used in building the annotation describing the interactive example.
In another aspect, computer software can be 5 developed by maintaining a body of source code for a computer-based application (e.g., an instructional example) and building the computer-based application based on the body of source code. Moreover, an annotation corresponding to the computer-based 10 application can be built based on information extracted from the body of source code. The body of source code that is maintained can include both program instructions and explanatory information, which programmers (or a processing script) can distinguish from each other based 15 symbols (e.g., markup symbols) appearing throughout the body of source code. The symbols can identify program instructions that are to be used for building interactive examples or source code fragments that are to be displayed to an end-user. Alternatively, or in addition, 20 the symbols can define a manner in which the explanatory information is to be presented to an end-user.
An annotation can be built by parsing the body of source code to identify portions of the source code that correspond to the annotation. Parsing can be 25 accomplished by processing the body of source code with a script that recognizes predetermined markup symbols appearing in the body of source code. Building of an annotation also may involve generating documentation source files based on a result of the parsing. The 30 documentation source files then can be compiled into a format recognized by an online help utility. Parsing of the source code also can be used to generate example source code files, which can be compiled into interactive examples that can be executed by an end-user.
Development of the software also may include generating a jump that allows an end-user to access the body of source code at a location corresponding to a source code fragment displayed adjacent to the jump.
5 Moreover, software development can include assembling a list of predetermined tokens (e.g., keywords or class names) appearing in the body of source code and generating a link to an online reference for each token in the assembled list.
Advantages may include one or more of the following. An instructional help system based on the documentation by example concept provides a learning environment, or laboratory, where users are provided with representative examples of proven techniques for 15 successfully operating the application to accomplish a desired goal (e.g., programming a new application). By executing, inspecting, modifying, and copying from the examples provided, users are able to learn complex and sophisticated subject matters at an accelerated rate.
The documentation by example system described here provides enhanced training and instruction capabilities.
Users can selectively execute any of several interactive examples and learn by observing their operation. In addition, a user's observations are reinforced by 25 annotations which are displayed to the user as the example is executing. The annotations are coordinated automatically with execution of the examples such that the annotation text displayed at any given time is synchronized with the state of the example. As a result, 30 the user can discern what just happened in the example by reading the annotation appearing on the screen.
Moreover, users can learn more about the example at a desired level of detail by following links in the annotation to relevant background information.
The manner in which the documentation by example system is built and maintained guarantees that the interactive examples and their respective annotations are kept in synchronization. Because the source code for the 5 interactive examples and the corresponding descriptive information are extracted directly from the same body of source code, the annotations always will reflect the current functionality of the interactive examples.
Moreover, by including the examples' source code and 10 their corresponding annotations within the same body of source code, maintenance of the documentation by example system is simplified dramatically. Because the components of the documentation by example system are integrated into, and updated along with, the interactive 15 examples' source code, software developers need not separately update and build the documentation by example system each time the examples are changed. As a result, the interactive examples can be updated freely and frequently without incurring the administrative headaches 20 o~ manually ensuring that the documentation system includes the most recent or correct versions of examples and their annotations.
Other advantages and features will become apparent from the following description, including the drawings 25 and claims.
Description of the Drawinqs Fig. 1 is a block diagram of a prior art computer system.
Fig. 2 shows display regions in a graphical user interface as used in the computer system of Fig. 1.
Figs. 3A through 5C are screen shots from a prior art online help and documentation system.
Fig. 6 is a flow diagram showing the options available to a user of the Informix~ by Example application.
Figs. 7 through 16E are screen shots from the Informix~ by Example application and from the NewEraTM
development environment.
Fig. 17 is a block diagram of the NewEraTM
architecture.
Fig. 18 is a block diagram showing how the Informix~ by Example application is built.
Fig. 19 is a sample of NewEraTM source code.
Detailed Description The help information provided by conventional online help systems has proven useful in aiding users to 15 make effective use of application programs. However, because these conventional online help systems essentially are limited to providing static textual or graphical information, their effectiveness is diminished considerably. Users of conventional online help systems 20 gain instruction by reading and carefully studying the textual and graphical information provided by the help system and then applying its teachings to the problem to be solved. As a result, learning to use applications of any complexity often is a painstaking and time consuming 25 process.
An online help and instruction system developed by Informix~ Software, Inc., known as NewEraTM by Example, dramatically enhances the ease with which users can absorb information and learn to use new applications.
30 NewEraTM by Example is an online documentation facility for NewEraTM, an object-oriented application development environment from Informix~ Software, Inc. which runs under the Windows 95/NT operating systems. A copy of NewEraTM by Example's online description of its use and operation is attached as Appendix A.
NewEraTM by Example (or more generally, Informix~
by Example, which covers the example-based instruction 5 systems provided for the NewEraTM, Visual Basic and Java development environments) is a specific implementation of a more general concept referred to as "documentation by example" in which users are provided with dynamic, interactive examples demonstrating how to accomplish a 10 given task. Annotations describing various aspects of the examples accompany the examples as they are being executed. Documentation by example is based in part on the premise that users learn best by doing something (e.g., participating in an activity and observing or influencing its outcome) rather than by merely reading about the topic.
As illustrated in the flow diagram of Fig. 6, an Informix3 by Example user has several different options for obtaining information including selecting among 20 various different topics (step 60); running examples while the application for which help is sought remains active (step 62); reading about the examples, either concurrently while running the example or independent of the example (step 64); inspecting the examples' source 25 code in different editor utilities (step 66); and accessing online background reference materials that help the user to understand the examples (step 68)--all without leaving the help environment. While in step 66, the source code for the examples can be used as sample 30 program code which can be cut-and-pasted for use as a template in the NewEraTM development environment in creating new applications. Moreover, Informix~ by Example enables users to learn through experimentation, e.g., by selectively changing the examples or their parameters and observing how the changes affect the examples' outcomes.
Specific features of Informix~ by Example are described in detail with reference to Figs. 7-16E, which 5 are exemplary screen shots taken from the Informix~ by Example application.
When a user first launches Informix~ by Example, the default screen configuration shown in Fig. 7 is displayed. This initial screen includes two separate 10 display windows, a list (or "table-of-contents") window 70 showing the subtopics presently available to the user under the current topic 73, and a text window 71 which displays the help information corresponding to the topic or subtopic selected from the list window 70. As the 15 user clicks different ones of the eight subtopics 72 displayed in the list window 70, the information in the text window 71 is updated automatically to correspond to the chosen subtopic 72. The user can move to different pages within the current topic by clicking the forward (">>") button 76 or the backward ("<<") button 75 as desired.
In the example of Fig. 7, the subtopics shown in the list window 71 relate to the topic "NewEraTM by Example Introductory Topics." To switch to another help 25 topic, and thereby make available a different subset of the online help documentation, the user clicks the Help Topics button 74 which brings up a window containing the Help Topics menu 80 with a list 82 of nine different help topics, as shown in Fig. 8. At any point in the Informix~ by Example application, the user can jump to any other portion of the online help system by bringing up the Help Topics menu 80 and clicking the desired topic. The user can return to a previous topic by pressing the Back button 77 an appropriate number of 35 times.
Each of the help topics in the list 82 in Fig. 8 can be expanded to reveal a hierarchy of multiple levels of subtopics. When the user clicks, for example, on topic 83 ("NewEraTM by Example"), it expands to reveal two 5 additional levels of subtopics as shown in Fig. 9--a first level 91 including the subtopics "Introduction,"
"Common NewEraTM Programming Techniques," and "The Examples," and a second level 93 under "The Examples"
subtopic which includes the 43 interactive examples.
When the user clicks one of the examples, e.g., the "Enabling and Disabling Buttons" example 95, the list window 70 is updated as shown in Fig. 10 to display the annotation segments 101 ("Overview of Buttons2 Example,"
Graphical Object Summary," "Event Handler Summary,"
"Important Event Handlers," and "Enhancements and Variations") associated with the selected example. The annotation segments 101 collectively describe the corresponding example and include descriptions of the example's window, its graphical objects, and its event 20 handlers. In addition to the prose descriptions of the example, an annotation segment usually also includes a source code fragment of particular interest which has been imported directly from the source code of the example under consideration.
As shown in Fig. 10, one of the annotation segments ("Important Event Handlers") includes 13 topics 104-- a list of the primary event handlers used in the BUTTONS2 example. Each event handler topic 104 includes source code fragments and prose explanations describing 30 the event handler to which the topic corresponds. For example, when the user clicks event handler topic 105, the text window 71 displays source code fragments 111 relating to the corresponding event handler (nextBT::
activate()) along with annotations 112 describing the 35 code's operation, as shown in Fig. 11.
The text window also may contain one or more links to related information, for example, background reference material, which in turn may include still further links to additional background information and so on in 5 hierarchical fashion, each successive level in the hierarchy providing information about the example in greater detail and at a lower level of abstraction. By providing a hierarchy of links to increasingly detailed documentation in this manner, Informix~ by Example 10 supplies context-appropriate information in a helpful and efficient manner to all users, regardless of their varying levels of experience and sophistication. A user can traverse down the hierarchical links of descriptive information selectively until a level of understanding is 15 reached that is commensurate with the user's needs and background. This arrangement provides novice users with easy access to detailed descriptive information while, at the same time, experienced users seeking help on a specific point are protected from having to navigate 20 through large volumes of unneeded information.
An example of hierarchical linking is shown in Fig. 10 in which text window 71 includes a link 106 (displayed as green, underlined text) to the MAIN() function, one of functions in the BUTTONS2 example. When 25 the user clicks the MAIN( ) function link 106, the text window 71 displays the source code 120 for that function, as shown in Fig. 12. The source code 120 includes further links to related information such as an online language reference manual containing descriptions of 30 keywords and object classes. When the user clicks one of these links--for example, the keyword link 122 for the LET statement--the text window 71 changes to display the corresponding online language reference entry as shown in Fig. 13A. Similarly, if the user had clicked the object 35 class link 123, the text window 71 would have displayed information about the ixSQLConnect class. In Fig. 13A, the user can follow links to still further background information, for example, by clicking the Object Expression box 134 to cause the text window 71 to appear 5 as in Fig. 13B. Subsequently, or alternatively, the user can click the Glossary button 133 to bring up an online glossary in a pair of windows--a glossary table of contents window 136 and a glossary text window 137--as shown in Fig. 13C. Clicking a term in the glossary table 10 of contents window 136 causes its definition to appear in the glossary text window 137.
After studying an example's annotation, its source code fragments, corresponding language reference entries, the glossary, or a combination thereof, the user can jump 15 selectively to any other location in the help system by clicking the Contents button 135, which brings up the Help Topics menu 80 shown in Fig. 8 (or the Index button 138, which presents the available help topics in a searchable-indexed form), and then selecting the desired 20 topic in the manner described in connection with Figs. 8 and 9.
Keyword links and class name links, such as the LET statement link 122 and the ixSQLConnect class link 123, respectively, in Fig. 12 are represented in visually 25 unique manners (e.g., blue uppercase text for keywords, blue upper and lowercase text for class names) so that they may be distinguished easily from each other and from other types of links such as the MAIN( ) function link 106 in Fig. 10 (green, underlined text). By using different 30 styles for different types of links, Informix~ by Example provides the user with intuitive and useful information concerning the nature of the online information available and the interrelationships between the different components (annotations, source code fragments, language 35 references, etc.) of the examples. Virtually any number CA 02242408 l998-07-06 of different link types may be represented by different styles according to the preferences of the system designer.
For each of the source code fragments included in 5 an example's annotation, a user can invoke an appropriate editing utility from within Informix~ by Example to inspect, edit or copy the example's source code. This allows users to view a source code fragment in the context of the larger program from which it was taken.
Informix~ by Example includes source code fragments from two different types of source code--textual program code in the NewEraTM programming language (as indicated by a 4GL or 4GH file suffix), and windows interface definition files (files having the suffix WIF) 15 which define how the GUI will appear to, and interact with, the end-user of the application undergoing development. To view either type of source code fragment, the user clicks a short-cut arrow next to a code fragment, for example, one of the short-cut arrows 20 107 and 108 shown in Figs. 10-12, and Informix~ by Example responds by launching an editor that corresponds to the type of source code under consideration. When the user clicks a short-cut arrow next to a 4GH or 4GL file, such as short-cut arrow 107 in Figs. 10 and 12, Informix~
25 by Example automatically launches the appropriate editor--NewEraTM Codewright--to view the source code file from which the code fragment was taken, as shown in Fig. 14 .
Similarly, when the user clicks a short-cut arrow next to a WIF file, such as short-cut arrow 108 in Figs. 10 and 30 11, Informix3 by Example automatically launches the appropriate editor--NewEraTM Window Painter 3.0--to view the WIF file from which the code fragment was taken, as shown in Fig. 15.
Selectively launching an appropriate one of 35 multiple different editors in this manner reflects the standard editing behavior of the NewEraTM development environment. Both the NewEraTM development environment and the Informix~ by Example documentation system make use of the same editors in the same manner. As a result, 5 users gain familiarity with the application for which help is sought (i.e., the NewEraTM development environment) through normal interaction with the online help system (i.e., Informix3 by Example).
Once the user has opened up the source code for an 10 example, the user simply can study the code or can cut-and-paste portions of the code, whether visual objects from a WIF file or program statements in a 4GH or 4GL
file, into the user's own source files. Alternatively, the user can perform a "Save As..." operation and thereby 15 save the source code for the example under a new file name. The user then can edit or otherwise manipulate the new file as desired. In this manner, the examples provided by Informix~ by Example can serve as templates for use in developing new applications in the NewEraTM
20 development environment.
Users also may execute any or all of the 43 interactive examples provided with Informix~ by Example to observe first hand how they operate. The examples are prebuilt and can be launched directly from their 25 corresponding Informix~ by Example annotations. To do so, a user first selects an example of interest from the Help Topics window 80 shown in Fig. 9 and, when the corresponding annotation appears in the text window, clicks the Run button appearing near the top of the text 30 window. In response, the example executes and, based on the input received from the user, displays various screens to the user as if the example were a standalone application. At the same time, the text window automatically updates to display descriptive information 35 that is pertinent to the portion of the example that was CA 02242408 l998-07-06 just executed by the user. With each successive operation that the user performs on the running example, the text window is updated simultaneously (or nearly so) to maintain synchronization with the state of the 5 interactive example by displaying corresponding sections of the annotations which explain to the user what just happened in the example. By coordinating the help display with the current state of the examples, users consistently are provided with timely and useful 10 information (e.g., the particular source code being executed by the example) that is directly relevant to the user's current topic of interest. As a result, the user's ability to comprehend and absorb information is enhanced dramatically. An example of Informix~ by 15 Example's automatically coordinated help display is illustrated in Figs. 16A-16E.
Fig. 16A shows the initial list window 70 and text window 71 that are displayed when the user selects the "Displaying an Edit Menu" example from the Help Topics 20 menu. To run this example, the user clicks the Run button 160 which, as shown in Fig. 16B, spawns an example window 161 illustrating the basics of an edit window. At the same time, the text window 71 is updated to display information on the MAIN( ) function for the "Displaying an 25 Edit Window" example.
As the user selectively manipulates the GUI
controls in the example window 161, the information displayed in the text window 71 is updated automatically in a corresponding manner. In Fig. 16C, the user has 30 clicked in text box 162 which causes the text window 71 to display information relating to editlTB:: focusln().
Similarly, when the user clicks text box 163, text window 71 displays information relating to edit2TB:: ~ocusln() as shown in Fig. 16D. When the user clicks the CheckBox 164, text window 71 displays information relating to noneditCB:: focusln() as shown in Fig. 16E.
Users can experiment with an example by changing its source code or modifying its parameters and observing 5 how these changes affect the example. To do so, the user edits the desired source code file, saves it a separate working directory so as not to disturb the predefined examples, and then rebuilds the example using mechanisms provided with the NewEraTM development environment. The 10 number and types of such experiments that can be created and performed are limited only by the imagination of the user.
Other options in running the examples are possible. For example, users can run an example without 15 concurrently viewing annotations. Additionally, the Debugger provided with NewEraTM can be used to set breakpoints in the example source code before running the example, thereby giving the user even further insight into how an example works.
A description of the Informix~ by Example architecture, and the manner in which the NewEraTM
development environment and the Informix~ by Example application are built, is provided with reference to Figs. 17-19.
Informix~ by Example builds upon the Online Help (OLH) facility provided with the Windows 95/NT operating systems. As shown in Fig. 17, the Informix~ by Example application 170 draws both upon resources created specifically for Informix~ by Example as well as 30 resources that are native to the NewEraTM development environment 179. The components specific to the Informix~ by Example application 170 include the interactive examples 171, source code 172 for the examples, and annotations 173 describing the examples.
35 The annotations 173 include several different subcomponents including representative fragments 174 of the examples' source code, short-cuts 175 that launch an appropriate editor (e.g., NewEraTM Codewright or NewEraTM
Window Painter) for viewing the examples' source code, 5 jumps 176 to the interactive examples, and links 177 to descriptions of specified keywords and class names contained in the NewEraTM online reference 185.
As indicated in Fig. 17, the online reference 185, the Codewright editor 181 and the Window Painter editor 10 182--along with other components such as Application Builder 180, Debugger 183 and Interprocess Communications (IPC) library 184--exist as part of the development environment 179 and thus are logically separated from the Informix~ by Example application 170. Consequently, when 15 a user of the Informix~ by Example application 170 requests a resource residing in the NewEraTM development environment--either by clicking a link 177 for a keyword or class name or by clicking a shortcut 175 to view source code--Informix~ by Example 170 first must 20 communicate with the NewEraTM development environment 179 via an interface dynamic linked library (DLL) 178 to access the requested resources. The interface DLL 178 is a compiled library of routines that enable the Informix~
by Example application 170 to communicate with other 25 applications such as the components of the development environment. Informix~ by Example 170 calls the appropriate DLL routines to display the requested online reference information or to launch the appropriate source code editor, depending on the nature of the request made 30 by the user.
More specifically, when an Informix~ by Example user clicks on a shortcut 175 to a location in an example's source code 172, the Informix~ by Example application 170 calls a function in the DLL, which in 35 turn calls a function in the IPC library 184 which CA 02242408 l998-07-06 launches the appropriate editor. As part of this function call (which is generated automatically by processing source code fragments during the build of Informix~ by Example, discussed below), the Informix~ by Example application 170 passes parameters that designate the editor to be launched (Codewright 181 or Window Painter 182), and that identify the line number at which the examples' source code 172 iS to be opened by the designated editor. When an Informix~ by Example user 10 clicks on a link 175 for a keyword or class name, the Informix~ by Example application 170 calls a function in the DLL, which in turn uses the Windows OLH facility to display the corresponding definition in the online reference 185.
Other functions provided by the interface DLL 178 control execution of the interactive examples 171 and coordinate the list window and the text window displays to ensure that they maintain correspondence. Further details on the interface DLL 178 and the runtime operation of the Informix~ by Example application 170 are set forth in Appendix B.
The manner in which the Informix~ by Example application 170 and its components (e.g., examples 171, examples' source code 172 and annotations 173) are generated realizes a high degree of code "maintainability"--a measure of the efficiency and ease with which an application can be, modified. The high degree of code maintainability is achieved by incorporating all of the information used to generate both the interactive examples and the corresponding annotative components of Informix~ by Example into a unified logical entity--namely, the source code for the interactive examples themselves. As a result, only one central source of information need be maintained. Any changes or updates made to that central information source will be incorporated automatically both into the examples and into the documentation / instruction / help facility (Informix~ by Example) for the examples. This automated build procedure ensures that the examples and 5 the corresponding Informix~ by Example annotations are kept in synchronization regardless of the number and frequency of modifications made to the underlying source code.
As shown in Fig. 18, the NewEraTM by Example source 10 code 400 can be thought of as a single logical entity, although physically it is formed of a collection of interdependent files. The source code 400 contains three basic types of text--program instructions 401, program comments 402 and annotations 403--intermixed throughout 15 the source code. The different text types are distinguished from each other by programming conventions and by strategically placing various different markup symbols 404 throughout the source code.
Some of the text in the source code 400 can serve 20 multiple purposes. For example, the program instructions 401 in the source code 400 are compiled into the examples' binary executable files 413. These program instructions include calls to the OLH facility to display the corresponding annotation at the appropriate point 25 during execution of the example. When an example is run by the end-user, these OLH calls cause the text window to display the appropriate annotation automatically to describe what just happened in the example.
Portions of these same program instructions 401 30 also will be extracted to serve as a clean copy of the examples' source code, which can be displayed to the user in an editing environment. Similarly, descriptive text that serves as program comments 402 (unprocessed programming explanations directed at the Informix~ by 35 Example project developers) also can serve as annotations 403 (programming explanations displayed to end-users of Informix~ by Example at runtime).
The markup symbols 404 delineate the various types of text in the source code and specify how they are to be 5 handled when the interactive examples and the Informix~
by Example annotations are built. Fig. 19 shows a sample of NewEraTM source code which includes several markup symbols including two instances of the ".normal" symbol 190 and 191, an ".[edit" symbol 192 and a ".]file" symbol 10 193. Each of these markup symbols, along with their respective arguments, are bounded by a pair of brackets ("{ ... }") indicating that they reside in comment fields and are not to be treated as NewEraTM program instructions. Programming languages other than NewEraTM
15 may use different conventions to delineate comment fields. In the Java programming language, for example, a start of a comment field is designated by a "/*" symbol and terminated by a "*/" symbol. In any event, the corresponding programming language compiler will ignore 20 any text that has been designated as residing in a comment field.
The ".normal" markup symbol indicates that the text following that symbol (e.g., "Since objects, ....,~
following symbol 190) is to be treated as explanatory 25 comments, and thus to be displayed to the end-user in a text window as part of the annotation text at an appropriate point during execution of a corresponding interactive example. Other markup symbols specify the name of output files, portions of the source code that 30 are to serve as representative fragments of the examples' source code, hotspots and destinations for jumps and links, or GUI-related information concerning display characteristics and objects ( windows, popups, buttons, etc.). A detailed description of the markup language is 35 set forth in Appendix C.
Once the source code 400 has been modified as desired, it is used to build the interactive examples and the descriptive content of the Informix3 by Example application through a number of different steps. First, 5 the source code 400 is processed by two different scripts 407--a PERL script (Practical Extraction and Report Language, a general purpose interpreted language often used for parsing text) and a WordBasic script. The scripts 407 generate two basic types of output: source 10 code files 411 for the interactive examples, and RTF
files 408 (Rich Text Format, the format expected by the OLH compiler) which represent the descriptive and visual content (e.g., annotations, source code fragments, shortcuts to source code editors, links to online 15 reference, jumps to executable examples) of the Informix~
by Example application.
The PERL script parses the source code 400 searching for markup symbols and, based on the particular markup symbols encountered, produces several RTF file 20 fragments and several source code files 411, which represent various subsets of the overall source code 400.
The WordBasic Script then merges the RTF file fragments into complete RTF files 408 which are processed by the Windows OLH compiler 409 to produce OLH files 410 25 containing the descriptive and visual content for the Informix~ by Example application. At the same time, the examples' source code 411 is compiled by the NewEraTM
compiler to generate the binary executable corresponding to the interactive examples 413.
The RTF file fragments generated by PERL script contain several different components in addition to the annotations 403 appearing in the source code 400. The PERL script identifies each instance of a keyword or a class name appearing in the source code extracted for the 35 examples. For each keyword and class name detected, the CA 02242408 l998-07-06 PERL script creates a link in the RTF file to the corresponding entry in the online reference materials.
The PERL script also extracts fragments of representative source code for inclusion in the RTF files as text that appears along with the explanatory comments.
The source code fragments are formatted as monospace unwrapped text delineated by leading and trailing blank lines whereas the explanatory comments are formatted as proportionally spaced wrapped text. For each source code 10 fragment included in the RTF file, the PERL script also inserts in the RTF file a corresponding short-cut button which enables the end-user to launch the source code editors and view the source code at the line where the fragment starts. The PERL script also strips all of the markup symbols 404 from the source code extracted for the examples. This provides end-users with a clean version of the source code for viewing in the associated editor.
Other functions performed by the PERL script include automatically guaranteeing that the identifier for an annotation topic is the same in an interactive example as it is in the Windows OLH facility. That is, the PERL script reads the help topic identifiers for the Windows OLH facility and generates corresponding NewEraTM
constants. The PERL script also generates modified versions of the NewEraTM makefiles (files that include computer-readable instructions for building an application) which are used to build the examples.
Further details of the PERL script and its operation are set forth in Appendix B.
Although the PERL and WordBasic scripts described above operate on source code written in the NewEraTM
programming language, different scripts can be used to parse other types of source code, for example, Java or Visual Basic. Generally, appropriate PERL and WordBasic 35 scripts can be written to process virtually any type of programming language provided the programming language utilizes ASCII source code (required by PERL) and provides some sort of source code comment mechanism.
Other programming language attributes that facilitate use 5 of the Informix~ by Example techniques include a mechanism for invoking the Windows OLH facility with a topic identifier (so the example can display its annotations), a mechanism for invoking the editing functions of the development environment (so the 10 annotation can open source code files, assuming the programming language under consideration provides or requires a development environment), and an online reference in Windows OLH format (so keywords in the source code can have jumps to the online reference).
15 Many of the Informix~ by Example features described above can be implemented even if the underlying programming language lacks one or more of these other attributes, however.
PERL scripts can be modified to output files in 20 formats other than RTF. For example, a modified PERL
script can output hypertext markup language (HTML) files, which can be viewed using any available web browser (e.g., Netscape Navigator).
Other variations of documentation by example are 25 possible. For example, the annotations describing the interactive examples could be presented in a manner other than textual. Sounds, graphical symbols, pictures, movies or any other means of communication could be used as desired. Further, the selection of which interactive 30 examples to perform could be based on factors other than, or in addition to, designation by the user. For example, an interactive example could be launched automatically at certain points during execution of the underlying application, or at certain execution points in the help 35 system. When the user clicks a keyword, class name or other link, an example could be launched automatically either in addition to, or instead of, displaying the textual reference information pointed to by the link.
The documentation by example methods and 5 techniques described above are not limited to aiding users of software development systems but rather may find application as a general training and education tool for any computer-based application or utility. Moreover, the techniques described here may be implemented in hardware 10 or software, or a combination of the two. Preferably, the techniques are implemented in computer programs executing on programmable computers that each includes a processor, a storage medium readable by the processor (including volatile and non-volatile memory and/or 15 storage elements), and suitable input and output devices.
Program code is applied to data entered using an input device to perform the functions described and to generate output information. The output information is applied to one or more output devices.
Each program is preferably implemented in a high level procedural or object-oriented programming language to communicate with a computer system. However, the programs can be implemented in assembly or machine language, if desired. In any case, the language may be a 25 compiled or interpreted language.
Each such computer program is preferably stored on a storage medium or device (e.g., CD-ROM, hard disk or magnetic diskette) that is readable by a general or special purpose programmable computer for configuring and 30 operating the computer when the storage medium or device is read by the computer to perform the procedures described. The system also may be implemented as a computer-readable storage medium, configured with a computer program, where the storage medium so configured causes a computer to operate in a specific and predefined manner.
Other embodiments are within the scope of the following claims.
ATTORNEY DOCKET NO: 07042/120001 COMPUTER-BASED DOCUMENTATION AND INSTRUCTION
Background This invention relates to computer-based documentation and instruction.
A typical computer system as shown in Fig. 1 includes a computer 11 having a central processing unit 12, an input/output unit 13 and a memory 14 containing 10 various programs used by the computer 11 such as an operating system 15 and one or more application programs 16. An end-user of the computer system communicates with the computer 11 by means of various input devices (keyboard 17, mouse 18) which transfer information to the 15 computer 11 via input/output unit 13. The computer 11 replies to this input data, among other ways, by providing responsive output to the end-user, for example, by displaying appropriate text and images on the screen of a display monitor 19.
The operating system 15 may include a graphical user interface ("GUI") by which the operating system and any applications it may be running (e.g., a word-processing program) can communicate with a user of the computer system. A commonly used GUI implementation 25 employs a desktop metaphor in which the screen of the monitor is regarded as a virtual desktop. The desktop is an essentially two-dimensional working template area supporting various graphical objects, including one or more display regions. As shown in Fig. 2, information 30 generated by application programs or the operating system can be displayed on the desktop 21 within display regions 23 (e.g., windows, dialog boxes, pop-up menus, pull-down menus, drop-down lists, icons). The user can interact with the operating system, and any applications it may be running, by manipulating the cursor 24 appropriately within the display regions and by entering information with the keyboard or other input device.
To use an application program effectively, a user 5 must know not only how to interact with the application itself, but depending on the nature of the application, the user also must possess a body of substantive knowledge relating to the subject matter to which the application pertains. For example, if the application is 10 a software development environment, the user must be familiar with computer programming concepts and programming languages to use the application effectively.
Most computer applications provide an online help / documentation facility which aids in the use of the 15 application. A typical online help system such as shown in Fig. 3A is accessed through a GUI in which screens of textual and graphical information are displayed to the user in a help window 30. The user can then read the screens of help text to get a better understanding of the 20 application and its various features.
The user invokes the help system with a key sequence (e.g., pressing the F1 key on the keyboard) or by clicking the mouse on an appropriate graphical icon or menu item. In response, the help system may display a 25 table of contents 31 listing the available help topics and subtopics which can be accessed and viewed by the user as desired. The user can browse through the table of contents 31 and click a help topic of interest to cause its corresponding body of information to be 30 displayed in a help window. In the help window 30 shown in Fig. 3A, the user has clicked the "Programming with Microsoft Word" topic 31 to cause the corresponding help screen 32 to be displayed in window 30 as shown in Fig.
3B.
-The "Programming with Microsoft Word" topic 31 shown in Fig. 3B includes several subtopics 33, each represented by a separate "link." When the user clicks the mouse on one of these links--for example, the "Error 5 Messages" link 34--the text for the corresponding help topic is displayed automatically in the help window 30, as shown in Fig. 3C. In this example, the "Error Messages'r topic 35 includes several links to further subtopics relating to specific types of error messages.
10 As shown in Fig. 3D, when the user clicks one of these links, for example, the "Out of memory (stack space)"
link 25, a new help window 36 is spawned to display the corresponding help information ("Freeing up memory") for the selected topic. The help information displayed in 15 window 36 includes yet another link 37 for another subtopic, "active window," which when clicked by the user causes corresponding help text to appear in a pop-up dialog box 38. Virtually any level of such nested help displays is possible. The quantity and types of display 20 regions (windows, dialog boxes, etc.) used to display help information is largely a matter of design choice based on the preferences of the help system developer.
A help system may provide "context-sensitive" help information, meaning that the help system automatically 25 displays help information specifically relevant to the application's current task, rather than simply displaying all available help topics and forcing the user to identify and call-up the appropriate help topic manually.
A context-sensitive help system decides which help 30 information to display based on factors such as the current state of the application (e.g., the particular function being invoked by the user) and the current cursor position.
The information provided by most online help 35 systems relates to the mechanics of using features of an application. In Fig. 4, for example, the text 42 corresponding to the chosen help topic 41, "Cancel printing," describes how to control the print feature provided by the application 40 (Microsoft Word).
A help system also may provide substantive information on how to make use of the application to achieve a desired goal. In Fig. 5A, for example, the online help system provides two types of substantive information: reference material 51 for the WordBasic 10 programming language and practical explanations 52 of how to use WordBasic to write useful programs. The reference material 51 includes textual annotations describing the syntax and meaning of various WordBasic statements, such as the A~A~7n statement, the help text for which is 15 shown in Fig. 5B. The practical explanations 52 can include static examples of program code which the user can study to gain a better understanding of the WordBasic programming language. Fig. 5C shows an example of program code that makes use of the GetCurValues WordBasic 20 statement.
Online help systems typically are "built" (i.e., processed into a form that facilitates run-time operation) by compiling several different help source files containing help information that has been composed 25 by technical writers. In general, these help source files are maintained as a separate body of information apart from the application to which the help system corresponds. Consequently, when the application developers change or update the functionality of the 30 application, the technical writers must make corresponding changes to the help source files to ensure that the online help system accurately describes the operation of the application.
Summary In one aspect, user instruction on a computer system involves performing an interactive example or instructional demonstration and providing, in 5 synchronization with the interactive example, explanatory information corresponding to the example. The explanatory information presented explains what most recently occurred in the interactive example and is updated automatically to correspond with the current 10 state of the interactive example. The explanatory information may be presented concurrently or simultaneously with output from the interactive example.
A user of the computer system is enabled to control the performance of the interactive example or the 15 presentation of explanatory information.
Presentation of the explanatory information can include displaying multiple windows on a screen of the computer system, the explanatory information being displayed in one window and the output from the interactive example being displayed in another window.
In response to a change in state of the interactive example, the explanatory information provided may be altered accordingly.
A user of the computer system also may be provided 25 with access to online reference materials relating to the interactive examples, the explanatory information, or both. The online reference materials may be accessed through links in the explanatory information. When a user selects a particular link, for example, by clicking 30 the link with a mouse cursor, corresponding reference information is presented to the user. The links in the explanatory information can be arranged in a logical hierarchy, each successive level in the hierarchy providing an increased degree of detail.
A user of the computer system also may be provided with access to source code associated with an interactive example. A fragment of source code associated with an interactive example may be displayed in an annotation 5 associated with the example. The annotation also may include a prose description of the interactive example's operation. Access to the source code can be provided by an editing utility, which can be launched when a user of the computer system selects a visually indicated jump (e.g., a short-cut arrow) within the annotation. The user then can view, copy or modify the source code fragment in the context of the source code for the entire interactive example. The user can experiment with an interactive example by iteratively modifying the 15 example's source code and then executing the modified example to see what happens.
An application for implementing concepts illustrated by the interactive examples may be provided to the user. The interactive examples provided by the 20 computer-based instructional system can represent a subset of the functionality provided by the application.
For example, the interactive examples may correspond to computer programming concepts. In that case, a software development environment may be provided to allow the user 25 to implement the programming concepts illustrated by the interactive examples.
The interactive examples and the corresponding annotations describing the interactive examples can be built from a unified body of source code. Markup 30 symbols, demarcating a portion of the source code to be used in building an interactive example and another portion of the source code to be used in building an annotation describing the interactive example, can be included in the unified body of source code. The portion 35 of the source code to be used in building an interactive example can overlap the portion of the source code to be used in building the annotation describing the interactive example.
In another aspect, computer software can be 5 developed by maintaining a body of source code for a computer-based application (e.g., an instructional example) and building the computer-based application based on the body of source code. Moreover, an annotation corresponding to the computer-based 10 application can be built based on information extracted from the body of source code. The body of source code that is maintained can include both program instructions and explanatory information, which programmers (or a processing script) can distinguish from each other based 15 symbols (e.g., markup symbols) appearing throughout the body of source code. The symbols can identify program instructions that are to be used for building interactive examples or source code fragments that are to be displayed to an end-user. Alternatively, or in addition, 20 the symbols can define a manner in which the explanatory information is to be presented to an end-user.
An annotation can be built by parsing the body of source code to identify portions of the source code that correspond to the annotation. Parsing can be 25 accomplished by processing the body of source code with a script that recognizes predetermined markup symbols appearing in the body of source code. Building of an annotation also may involve generating documentation source files based on a result of the parsing. The 30 documentation source files then can be compiled into a format recognized by an online help utility. Parsing of the source code also can be used to generate example source code files, which can be compiled into interactive examples that can be executed by an end-user.
Development of the software also may include generating a jump that allows an end-user to access the body of source code at a location corresponding to a source code fragment displayed adjacent to the jump.
5 Moreover, software development can include assembling a list of predetermined tokens (e.g., keywords or class names) appearing in the body of source code and generating a link to an online reference for each token in the assembled list.
Advantages may include one or more of the following. An instructional help system based on the documentation by example concept provides a learning environment, or laboratory, where users are provided with representative examples of proven techniques for 15 successfully operating the application to accomplish a desired goal (e.g., programming a new application). By executing, inspecting, modifying, and copying from the examples provided, users are able to learn complex and sophisticated subject matters at an accelerated rate.
The documentation by example system described here provides enhanced training and instruction capabilities.
Users can selectively execute any of several interactive examples and learn by observing their operation. In addition, a user's observations are reinforced by 25 annotations which are displayed to the user as the example is executing. The annotations are coordinated automatically with execution of the examples such that the annotation text displayed at any given time is synchronized with the state of the example. As a result, 30 the user can discern what just happened in the example by reading the annotation appearing on the screen.
Moreover, users can learn more about the example at a desired level of detail by following links in the annotation to relevant background information.
The manner in which the documentation by example system is built and maintained guarantees that the interactive examples and their respective annotations are kept in synchronization. Because the source code for the 5 interactive examples and the corresponding descriptive information are extracted directly from the same body of source code, the annotations always will reflect the current functionality of the interactive examples.
Moreover, by including the examples' source code and 10 their corresponding annotations within the same body of source code, maintenance of the documentation by example system is simplified dramatically. Because the components of the documentation by example system are integrated into, and updated along with, the interactive 15 examples' source code, software developers need not separately update and build the documentation by example system each time the examples are changed. As a result, the interactive examples can be updated freely and frequently without incurring the administrative headaches 20 o~ manually ensuring that the documentation system includes the most recent or correct versions of examples and their annotations.
Other advantages and features will become apparent from the following description, including the drawings 25 and claims.
Description of the Drawinqs Fig. 1 is a block diagram of a prior art computer system.
Fig. 2 shows display regions in a graphical user interface as used in the computer system of Fig. 1.
Figs. 3A through 5C are screen shots from a prior art online help and documentation system.
Fig. 6 is a flow diagram showing the options available to a user of the Informix~ by Example application.
Figs. 7 through 16E are screen shots from the Informix~ by Example application and from the NewEraTM
development environment.
Fig. 17 is a block diagram of the NewEraTM
architecture.
Fig. 18 is a block diagram showing how the Informix~ by Example application is built.
Fig. 19 is a sample of NewEraTM source code.
Detailed Description The help information provided by conventional online help systems has proven useful in aiding users to 15 make effective use of application programs. However, because these conventional online help systems essentially are limited to providing static textual or graphical information, their effectiveness is diminished considerably. Users of conventional online help systems 20 gain instruction by reading and carefully studying the textual and graphical information provided by the help system and then applying its teachings to the problem to be solved. As a result, learning to use applications of any complexity often is a painstaking and time consuming 25 process.
An online help and instruction system developed by Informix~ Software, Inc., known as NewEraTM by Example, dramatically enhances the ease with which users can absorb information and learn to use new applications.
30 NewEraTM by Example is an online documentation facility for NewEraTM, an object-oriented application development environment from Informix~ Software, Inc. which runs under the Windows 95/NT operating systems. A copy of NewEraTM by Example's online description of its use and operation is attached as Appendix A.
NewEraTM by Example (or more generally, Informix~
by Example, which covers the example-based instruction 5 systems provided for the NewEraTM, Visual Basic and Java development environments) is a specific implementation of a more general concept referred to as "documentation by example" in which users are provided with dynamic, interactive examples demonstrating how to accomplish a 10 given task. Annotations describing various aspects of the examples accompany the examples as they are being executed. Documentation by example is based in part on the premise that users learn best by doing something (e.g., participating in an activity and observing or influencing its outcome) rather than by merely reading about the topic.
As illustrated in the flow diagram of Fig. 6, an Informix3 by Example user has several different options for obtaining information including selecting among 20 various different topics (step 60); running examples while the application for which help is sought remains active (step 62); reading about the examples, either concurrently while running the example or independent of the example (step 64); inspecting the examples' source 25 code in different editor utilities (step 66); and accessing online background reference materials that help the user to understand the examples (step 68)--all without leaving the help environment. While in step 66, the source code for the examples can be used as sample 30 program code which can be cut-and-pasted for use as a template in the NewEraTM development environment in creating new applications. Moreover, Informix~ by Example enables users to learn through experimentation, e.g., by selectively changing the examples or their parameters and observing how the changes affect the examples' outcomes.
Specific features of Informix~ by Example are described in detail with reference to Figs. 7-16E, which 5 are exemplary screen shots taken from the Informix~ by Example application.
When a user first launches Informix~ by Example, the default screen configuration shown in Fig. 7 is displayed. This initial screen includes two separate 10 display windows, a list (or "table-of-contents") window 70 showing the subtopics presently available to the user under the current topic 73, and a text window 71 which displays the help information corresponding to the topic or subtopic selected from the list window 70. As the 15 user clicks different ones of the eight subtopics 72 displayed in the list window 70, the information in the text window 71 is updated automatically to correspond to the chosen subtopic 72. The user can move to different pages within the current topic by clicking the forward (">>") button 76 or the backward ("<<") button 75 as desired.
In the example of Fig. 7, the subtopics shown in the list window 71 relate to the topic "NewEraTM by Example Introductory Topics." To switch to another help 25 topic, and thereby make available a different subset of the online help documentation, the user clicks the Help Topics button 74 which brings up a window containing the Help Topics menu 80 with a list 82 of nine different help topics, as shown in Fig. 8. At any point in the Informix~ by Example application, the user can jump to any other portion of the online help system by bringing up the Help Topics menu 80 and clicking the desired topic. The user can return to a previous topic by pressing the Back button 77 an appropriate number of 35 times.
Each of the help topics in the list 82 in Fig. 8 can be expanded to reveal a hierarchy of multiple levels of subtopics. When the user clicks, for example, on topic 83 ("NewEraTM by Example"), it expands to reveal two 5 additional levels of subtopics as shown in Fig. 9--a first level 91 including the subtopics "Introduction,"
"Common NewEraTM Programming Techniques," and "The Examples," and a second level 93 under "The Examples"
subtopic which includes the 43 interactive examples.
When the user clicks one of the examples, e.g., the "Enabling and Disabling Buttons" example 95, the list window 70 is updated as shown in Fig. 10 to display the annotation segments 101 ("Overview of Buttons2 Example,"
Graphical Object Summary," "Event Handler Summary,"
"Important Event Handlers," and "Enhancements and Variations") associated with the selected example. The annotation segments 101 collectively describe the corresponding example and include descriptions of the example's window, its graphical objects, and its event 20 handlers. In addition to the prose descriptions of the example, an annotation segment usually also includes a source code fragment of particular interest which has been imported directly from the source code of the example under consideration.
As shown in Fig. 10, one of the annotation segments ("Important Event Handlers") includes 13 topics 104-- a list of the primary event handlers used in the BUTTONS2 example. Each event handler topic 104 includes source code fragments and prose explanations describing 30 the event handler to which the topic corresponds. For example, when the user clicks event handler topic 105, the text window 71 displays source code fragments 111 relating to the corresponding event handler (nextBT::
activate()) along with annotations 112 describing the 35 code's operation, as shown in Fig. 11.
The text window also may contain one or more links to related information, for example, background reference material, which in turn may include still further links to additional background information and so on in 5 hierarchical fashion, each successive level in the hierarchy providing information about the example in greater detail and at a lower level of abstraction. By providing a hierarchy of links to increasingly detailed documentation in this manner, Informix~ by Example 10 supplies context-appropriate information in a helpful and efficient manner to all users, regardless of their varying levels of experience and sophistication. A user can traverse down the hierarchical links of descriptive information selectively until a level of understanding is 15 reached that is commensurate with the user's needs and background. This arrangement provides novice users with easy access to detailed descriptive information while, at the same time, experienced users seeking help on a specific point are protected from having to navigate 20 through large volumes of unneeded information.
An example of hierarchical linking is shown in Fig. 10 in which text window 71 includes a link 106 (displayed as green, underlined text) to the MAIN() function, one of functions in the BUTTONS2 example. When 25 the user clicks the MAIN( ) function link 106, the text window 71 displays the source code 120 for that function, as shown in Fig. 12. The source code 120 includes further links to related information such as an online language reference manual containing descriptions of 30 keywords and object classes. When the user clicks one of these links--for example, the keyword link 122 for the LET statement--the text window 71 changes to display the corresponding online language reference entry as shown in Fig. 13A. Similarly, if the user had clicked the object 35 class link 123, the text window 71 would have displayed information about the ixSQLConnect class. In Fig. 13A, the user can follow links to still further background information, for example, by clicking the Object Expression box 134 to cause the text window 71 to appear 5 as in Fig. 13B. Subsequently, or alternatively, the user can click the Glossary button 133 to bring up an online glossary in a pair of windows--a glossary table of contents window 136 and a glossary text window 137--as shown in Fig. 13C. Clicking a term in the glossary table 10 of contents window 136 causes its definition to appear in the glossary text window 137.
After studying an example's annotation, its source code fragments, corresponding language reference entries, the glossary, or a combination thereof, the user can jump 15 selectively to any other location in the help system by clicking the Contents button 135, which brings up the Help Topics menu 80 shown in Fig. 8 (or the Index button 138, which presents the available help topics in a searchable-indexed form), and then selecting the desired 20 topic in the manner described in connection with Figs. 8 and 9.
Keyword links and class name links, such as the LET statement link 122 and the ixSQLConnect class link 123, respectively, in Fig. 12 are represented in visually 25 unique manners (e.g., blue uppercase text for keywords, blue upper and lowercase text for class names) so that they may be distinguished easily from each other and from other types of links such as the MAIN( ) function link 106 in Fig. 10 (green, underlined text). By using different 30 styles for different types of links, Informix~ by Example provides the user with intuitive and useful information concerning the nature of the online information available and the interrelationships between the different components (annotations, source code fragments, language 35 references, etc.) of the examples. Virtually any number CA 02242408 l998-07-06 of different link types may be represented by different styles according to the preferences of the system designer.
For each of the source code fragments included in 5 an example's annotation, a user can invoke an appropriate editing utility from within Informix~ by Example to inspect, edit or copy the example's source code. This allows users to view a source code fragment in the context of the larger program from which it was taken.
Informix~ by Example includes source code fragments from two different types of source code--textual program code in the NewEraTM programming language (as indicated by a 4GL or 4GH file suffix), and windows interface definition files (files having the suffix WIF) 15 which define how the GUI will appear to, and interact with, the end-user of the application undergoing development. To view either type of source code fragment, the user clicks a short-cut arrow next to a code fragment, for example, one of the short-cut arrows 20 107 and 108 shown in Figs. 10-12, and Informix~ by Example responds by launching an editor that corresponds to the type of source code under consideration. When the user clicks a short-cut arrow next to a 4GH or 4GL file, such as short-cut arrow 107 in Figs. 10 and 12, Informix~
25 by Example automatically launches the appropriate editor--NewEraTM Codewright--to view the source code file from which the code fragment was taken, as shown in Fig. 14 .
Similarly, when the user clicks a short-cut arrow next to a WIF file, such as short-cut arrow 108 in Figs. 10 and 30 11, Informix3 by Example automatically launches the appropriate editor--NewEraTM Window Painter 3.0--to view the WIF file from which the code fragment was taken, as shown in Fig. 15.
Selectively launching an appropriate one of 35 multiple different editors in this manner reflects the standard editing behavior of the NewEraTM development environment. Both the NewEraTM development environment and the Informix~ by Example documentation system make use of the same editors in the same manner. As a result, 5 users gain familiarity with the application for which help is sought (i.e., the NewEraTM development environment) through normal interaction with the online help system (i.e., Informix3 by Example).
Once the user has opened up the source code for an 10 example, the user simply can study the code or can cut-and-paste portions of the code, whether visual objects from a WIF file or program statements in a 4GH or 4GL
file, into the user's own source files. Alternatively, the user can perform a "Save As..." operation and thereby 15 save the source code for the example under a new file name. The user then can edit or otherwise manipulate the new file as desired. In this manner, the examples provided by Informix~ by Example can serve as templates for use in developing new applications in the NewEraTM
20 development environment.
Users also may execute any or all of the 43 interactive examples provided with Informix~ by Example to observe first hand how they operate. The examples are prebuilt and can be launched directly from their 25 corresponding Informix~ by Example annotations. To do so, a user first selects an example of interest from the Help Topics window 80 shown in Fig. 9 and, when the corresponding annotation appears in the text window, clicks the Run button appearing near the top of the text 30 window. In response, the example executes and, based on the input received from the user, displays various screens to the user as if the example were a standalone application. At the same time, the text window automatically updates to display descriptive information 35 that is pertinent to the portion of the example that was CA 02242408 l998-07-06 just executed by the user. With each successive operation that the user performs on the running example, the text window is updated simultaneously (or nearly so) to maintain synchronization with the state of the 5 interactive example by displaying corresponding sections of the annotations which explain to the user what just happened in the example. By coordinating the help display with the current state of the examples, users consistently are provided with timely and useful 10 information (e.g., the particular source code being executed by the example) that is directly relevant to the user's current topic of interest. As a result, the user's ability to comprehend and absorb information is enhanced dramatically. An example of Informix~ by 15 Example's automatically coordinated help display is illustrated in Figs. 16A-16E.
Fig. 16A shows the initial list window 70 and text window 71 that are displayed when the user selects the "Displaying an Edit Menu" example from the Help Topics 20 menu. To run this example, the user clicks the Run button 160 which, as shown in Fig. 16B, spawns an example window 161 illustrating the basics of an edit window. At the same time, the text window 71 is updated to display information on the MAIN( ) function for the "Displaying an 25 Edit Window" example.
As the user selectively manipulates the GUI
controls in the example window 161, the information displayed in the text window 71 is updated automatically in a corresponding manner. In Fig. 16C, the user has 30 clicked in text box 162 which causes the text window 71 to display information relating to editlTB:: focusln().
Similarly, when the user clicks text box 163, text window 71 displays information relating to edit2TB:: ~ocusln() as shown in Fig. 16D. When the user clicks the CheckBox 164, text window 71 displays information relating to noneditCB:: focusln() as shown in Fig. 16E.
Users can experiment with an example by changing its source code or modifying its parameters and observing 5 how these changes affect the example. To do so, the user edits the desired source code file, saves it a separate working directory so as not to disturb the predefined examples, and then rebuilds the example using mechanisms provided with the NewEraTM development environment. The 10 number and types of such experiments that can be created and performed are limited only by the imagination of the user.
Other options in running the examples are possible. For example, users can run an example without 15 concurrently viewing annotations. Additionally, the Debugger provided with NewEraTM can be used to set breakpoints in the example source code before running the example, thereby giving the user even further insight into how an example works.
A description of the Informix~ by Example architecture, and the manner in which the NewEraTM
development environment and the Informix~ by Example application are built, is provided with reference to Figs. 17-19.
Informix~ by Example builds upon the Online Help (OLH) facility provided with the Windows 95/NT operating systems. As shown in Fig. 17, the Informix~ by Example application 170 draws both upon resources created specifically for Informix~ by Example as well as 30 resources that are native to the NewEraTM development environment 179. The components specific to the Informix~ by Example application 170 include the interactive examples 171, source code 172 for the examples, and annotations 173 describing the examples.
35 The annotations 173 include several different subcomponents including representative fragments 174 of the examples' source code, short-cuts 175 that launch an appropriate editor (e.g., NewEraTM Codewright or NewEraTM
Window Painter) for viewing the examples' source code, 5 jumps 176 to the interactive examples, and links 177 to descriptions of specified keywords and class names contained in the NewEraTM online reference 185.
As indicated in Fig. 17, the online reference 185, the Codewright editor 181 and the Window Painter editor 10 182--along with other components such as Application Builder 180, Debugger 183 and Interprocess Communications (IPC) library 184--exist as part of the development environment 179 and thus are logically separated from the Informix~ by Example application 170. Consequently, when 15 a user of the Informix~ by Example application 170 requests a resource residing in the NewEraTM development environment--either by clicking a link 177 for a keyword or class name or by clicking a shortcut 175 to view source code--Informix~ by Example 170 first must 20 communicate with the NewEraTM development environment 179 via an interface dynamic linked library (DLL) 178 to access the requested resources. The interface DLL 178 is a compiled library of routines that enable the Informix~
by Example application 170 to communicate with other 25 applications such as the components of the development environment. Informix~ by Example 170 calls the appropriate DLL routines to display the requested online reference information or to launch the appropriate source code editor, depending on the nature of the request made 30 by the user.
More specifically, when an Informix~ by Example user clicks on a shortcut 175 to a location in an example's source code 172, the Informix~ by Example application 170 calls a function in the DLL, which in 35 turn calls a function in the IPC library 184 which CA 02242408 l998-07-06 launches the appropriate editor. As part of this function call (which is generated automatically by processing source code fragments during the build of Informix~ by Example, discussed below), the Informix~ by Example application 170 passes parameters that designate the editor to be launched (Codewright 181 or Window Painter 182), and that identify the line number at which the examples' source code 172 iS to be opened by the designated editor. When an Informix~ by Example user 10 clicks on a link 175 for a keyword or class name, the Informix~ by Example application 170 calls a function in the DLL, which in turn uses the Windows OLH facility to display the corresponding definition in the online reference 185.
Other functions provided by the interface DLL 178 control execution of the interactive examples 171 and coordinate the list window and the text window displays to ensure that they maintain correspondence. Further details on the interface DLL 178 and the runtime operation of the Informix~ by Example application 170 are set forth in Appendix B.
The manner in which the Informix~ by Example application 170 and its components (e.g., examples 171, examples' source code 172 and annotations 173) are generated realizes a high degree of code "maintainability"--a measure of the efficiency and ease with which an application can be, modified. The high degree of code maintainability is achieved by incorporating all of the information used to generate both the interactive examples and the corresponding annotative components of Informix~ by Example into a unified logical entity--namely, the source code for the interactive examples themselves. As a result, only one central source of information need be maintained. Any changes or updates made to that central information source will be incorporated automatically both into the examples and into the documentation / instruction / help facility (Informix~ by Example) for the examples. This automated build procedure ensures that the examples and 5 the corresponding Informix~ by Example annotations are kept in synchronization regardless of the number and frequency of modifications made to the underlying source code.
As shown in Fig. 18, the NewEraTM by Example source 10 code 400 can be thought of as a single logical entity, although physically it is formed of a collection of interdependent files. The source code 400 contains three basic types of text--program instructions 401, program comments 402 and annotations 403--intermixed throughout 15 the source code. The different text types are distinguished from each other by programming conventions and by strategically placing various different markup symbols 404 throughout the source code.
Some of the text in the source code 400 can serve 20 multiple purposes. For example, the program instructions 401 in the source code 400 are compiled into the examples' binary executable files 413. These program instructions include calls to the OLH facility to display the corresponding annotation at the appropriate point 25 during execution of the example. When an example is run by the end-user, these OLH calls cause the text window to display the appropriate annotation automatically to describe what just happened in the example.
Portions of these same program instructions 401 30 also will be extracted to serve as a clean copy of the examples' source code, which can be displayed to the user in an editing environment. Similarly, descriptive text that serves as program comments 402 (unprocessed programming explanations directed at the Informix~ by 35 Example project developers) also can serve as annotations 403 (programming explanations displayed to end-users of Informix~ by Example at runtime).
The markup symbols 404 delineate the various types of text in the source code and specify how they are to be 5 handled when the interactive examples and the Informix~
by Example annotations are built. Fig. 19 shows a sample of NewEraTM source code which includes several markup symbols including two instances of the ".normal" symbol 190 and 191, an ".[edit" symbol 192 and a ".]file" symbol 10 193. Each of these markup symbols, along with their respective arguments, are bounded by a pair of brackets ("{ ... }") indicating that they reside in comment fields and are not to be treated as NewEraTM program instructions. Programming languages other than NewEraTM
15 may use different conventions to delineate comment fields. In the Java programming language, for example, a start of a comment field is designated by a "/*" symbol and terminated by a "*/" symbol. In any event, the corresponding programming language compiler will ignore 20 any text that has been designated as residing in a comment field.
The ".normal" markup symbol indicates that the text following that symbol (e.g., "Since objects, ....,~
following symbol 190) is to be treated as explanatory 25 comments, and thus to be displayed to the end-user in a text window as part of the annotation text at an appropriate point during execution of a corresponding interactive example. Other markup symbols specify the name of output files, portions of the source code that 30 are to serve as representative fragments of the examples' source code, hotspots and destinations for jumps and links, or GUI-related information concerning display characteristics and objects ( windows, popups, buttons, etc.). A detailed description of the markup language is 35 set forth in Appendix C.
Once the source code 400 has been modified as desired, it is used to build the interactive examples and the descriptive content of the Informix3 by Example application through a number of different steps. First, 5 the source code 400 is processed by two different scripts 407--a PERL script (Practical Extraction and Report Language, a general purpose interpreted language often used for parsing text) and a WordBasic script. The scripts 407 generate two basic types of output: source 10 code files 411 for the interactive examples, and RTF
files 408 (Rich Text Format, the format expected by the OLH compiler) which represent the descriptive and visual content (e.g., annotations, source code fragments, shortcuts to source code editors, links to online 15 reference, jumps to executable examples) of the Informix~
by Example application.
The PERL script parses the source code 400 searching for markup symbols and, based on the particular markup symbols encountered, produces several RTF file 20 fragments and several source code files 411, which represent various subsets of the overall source code 400.
The WordBasic Script then merges the RTF file fragments into complete RTF files 408 which are processed by the Windows OLH compiler 409 to produce OLH files 410 25 containing the descriptive and visual content for the Informix~ by Example application. At the same time, the examples' source code 411 is compiled by the NewEraTM
compiler to generate the binary executable corresponding to the interactive examples 413.
The RTF file fragments generated by PERL script contain several different components in addition to the annotations 403 appearing in the source code 400. The PERL script identifies each instance of a keyword or a class name appearing in the source code extracted for the 35 examples. For each keyword and class name detected, the CA 02242408 l998-07-06 PERL script creates a link in the RTF file to the corresponding entry in the online reference materials.
The PERL script also extracts fragments of representative source code for inclusion in the RTF files as text that appears along with the explanatory comments.
The source code fragments are formatted as monospace unwrapped text delineated by leading and trailing blank lines whereas the explanatory comments are formatted as proportionally spaced wrapped text. For each source code 10 fragment included in the RTF file, the PERL script also inserts in the RTF file a corresponding short-cut button which enables the end-user to launch the source code editors and view the source code at the line where the fragment starts. The PERL script also strips all of the markup symbols 404 from the source code extracted for the examples. This provides end-users with a clean version of the source code for viewing in the associated editor.
Other functions performed by the PERL script include automatically guaranteeing that the identifier for an annotation topic is the same in an interactive example as it is in the Windows OLH facility. That is, the PERL script reads the help topic identifiers for the Windows OLH facility and generates corresponding NewEraTM
constants. The PERL script also generates modified versions of the NewEraTM makefiles (files that include computer-readable instructions for building an application) which are used to build the examples.
Further details of the PERL script and its operation are set forth in Appendix B.
Although the PERL and WordBasic scripts described above operate on source code written in the NewEraTM
programming language, different scripts can be used to parse other types of source code, for example, Java or Visual Basic. Generally, appropriate PERL and WordBasic 35 scripts can be written to process virtually any type of programming language provided the programming language utilizes ASCII source code (required by PERL) and provides some sort of source code comment mechanism.
Other programming language attributes that facilitate use 5 of the Informix~ by Example techniques include a mechanism for invoking the Windows OLH facility with a topic identifier (so the example can display its annotations), a mechanism for invoking the editing functions of the development environment (so the 10 annotation can open source code files, assuming the programming language under consideration provides or requires a development environment), and an online reference in Windows OLH format (so keywords in the source code can have jumps to the online reference).
15 Many of the Informix~ by Example features described above can be implemented even if the underlying programming language lacks one or more of these other attributes, however.
PERL scripts can be modified to output files in 20 formats other than RTF. For example, a modified PERL
script can output hypertext markup language (HTML) files, which can be viewed using any available web browser (e.g., Netscape Navigator).
Other variations of documentation by example are 25 possible. For example, the annotations describing the interactive examples could be presented in a manner other than textual. Sounds, graphical symbols, pictures, movies or any other means of communication could be used as desired. Further, the selection of which interactive 30 examples to perform could be based on factors other than, or in addition to, designation by the user. For example, an interactive example could be launched automatically at certain points during execution of the underlying application, or at certain execution points in the help 35 system. When the user clicks a keyword, class name or other link, an example could be launched automatically either in addition to, or instead of, displaying the textual reference information pointed to by the link.
The documentation by example methods and 5 techniques described above are not limited to aiding users of software development systems but rather may find application as a general training and education tool for any computer-based application or utility. Moreover, the techniques described here may be implemented in hardware 10 or software, or a combination of the two. Preferably, the techniques are implemented in computer programs executing on programmable computers that each includes a processor, a storage medium readable by the processor (including volatile and non-volatile memory and/or 15 storage elements), and suitable input and output devices.
Program code is applied to data entered using an input device to perform the functions described and to generate output information. The output information is applied to one or more output devices.
Each program is preferably implemented in a high level procedural or object-oriented programming language to communicate with a computer system. However, the programs can be implemented in assembly or machine language, if desired. In any case, the language may be a 25 compiled or interpreted language.
Each such computer program is preferably stored on a storage medium or device (e.g., CD-ROM, hard disk or magnetic diskette) that is readable by a general or special purpose programmable computer for configuring and 30 operating the computer when the storage medium or device is read by the computer to perform the procedures described. The system also may be implemented as a computer-readable storage medium, configured with a computer program, where the storage medium so configured causes a computer to operate in a specific and predefined manner.
Other embodiments are within the scope of the following claims.
Claims (60)
1. A method, performed on a computer system, of instructing a user, the method comprising:
performing an interactive example; and providing, in synchronization with the interactive example, explanatory information corresponding to the interactive example.
performing an interactive example; and providing, in synchronization with the interactive example, explanatory information corresponding to the interactive example.
2. The method of claim 1 further comprising enabling a user of the computer system to control the performance of the interactive example.
3. The method of claim 1 further comprising enabling a user of the computer system to control the provision of explanatory information.
4. The method of claim 1 in which the providing comprises presenting explanatory information that explains what most recently occurred in the interactive example.
5. The method of claim 4 in which the providing comprises presenting the explanatory information concurrently with output from the interactive example.
6. The method of claim 5 in which the providing comprises displaying multiple windows on a screen of the computer system, the explanatory information being displayed in one window and the output from the interactive example being displayed in another window.
7. The method of claim 1 in which the providing comprises altering the explanatory information provided in response to a change in state of the interactive example.
8. The method of claim 1 further comprising providing a user of the computer system with access to online reference materials relating to the interactive examples, the explanatory information, or both.
9. The method of claim 8 further comprising providing links in the explanatory information to the online reference materials.
10. The method of claim 9 further comprising presenting corresponding reference information when a user of the computer system selects a link.
11. The method of claim 9 in which the links in the explanatory information are arranged in a logical hierarchy, each successive level in the hierarchy providing an increased degree of detail.
12. The method of claim 1 further comprising providing a user of the computer system with access to source code associated with an interactive example.
13. The method of claim 12 further comprising enabling the user to view, copy or modify source code associated with an interactive example.
14. The method of claim 1 further comprising enabling a user of the computer system to modify an interactive example.
15. The method of claim 14 further comprising allowing the user to iteratively modify and execute an interactive example.
16. The method of claim 1 further comprising providing in the explanatory information a jump to a utility for accessing source code associated with an interactive example.
17. The method of claim 16 further comprising launching the utility for accessing the source code when a user of the computer system selects the jump.
18. The method of claim 1 in which the providing comprises presenting a prose description of the interactive example's operation.
19. The method of claim 1 in which the providing comprises presenting a fragment of source code associated with the interactive example.
20. The method of claim 19 further comprising enabling a user of the computer system to view the source code fragment in a context of source code for the entire interactive example.
21. A computer-based method of educating a user of a computer system, the method comprising:
performing an interactive demonstration relating to a selected topic;
presenting the user with an annotation descriptive of the interactive demonstration in coordination with performance of the interactive demonstration; and allowing the user to selectively explore different aspects of the interactive demonstration, the annotation, or both.
performing an interactive demonstration relating to a selected topic;
presenting the user with an annotation descriptive of the interactive demonstration in coordination with performance of the interactive demonstration; and allowing the user to selectively explore different aspects of the interactive demonstration, the annotation, or both.
22. A computer-based instructional system comprising:
an interactive example selectively executable by a user of a computer system; and annotations describing the interactive example, different annotations being provided automatically in response to selective execution of the interactive example.
an interactive example selectively executable by a user of a computer system; and annotations describing the interactive example, different annotations being provided automatically in response to selective execution of the interactive example.
23. The system of claim 22 further comprising a utility through which the user can access source code associated with the interactive example.
24. The system of claim 23 in which the utility enables the user to view, copy or modify the interactive example's source code.
25. The system of claim 22 further comprising a body of reference information selectively accessible to the user.
26. The system of claim 25 further comprising a link that provides the user with direct access to an item of information within the body of reference information.
27. The system of claim 26 in which the link is a visually indicated marker on which the user can click a cursor.
28. The system of claim 22 in which the annotations comprise textual descriptions of the interactive example.
29. The system of claim 28 in which the annotations comprise fragments of source code associated with the interactive example.
30. The system of claim 29 in which the annotations comprise jumps to a utility through which the user can access the complete source code associated with the interactive example.
31. The system of claim 30 in which the jumps are represented visually to the user as short-cut arrows.
32. The system of claim 22 in which the annotations comprise visually indicated links to a body of reference information.
33. The system of claim 22 in which the interactive example illustrates computer programming concepts.
34. The system of claim 33 further comprising a software development environment for implementing the programming concepts illustrated by the interactive example.
35. The system of claim 22 in which a unified body of source code is used to build the interactive example and the annotations describing the interactive example.
36. The system of claim 35 in which the unified body of source code includes markup symbols demarcating a portion of the source code to be used in building the interactive example and another portion of the source code to be used in building the annotations describing the interactive example.
37. The system of claim 36 in which the portion of the source code to be used in building the interactive example overlaps the portion of the source code to be used in building the annotations describing the interactive example.
38. The system of claim 22 further comprising an application for implementing concepts illustrated by the interactive example.
39. The system of claim 38 in which the interactive example provided by the computer-based instructional system represents a subset of the functionality provided by the application.
40. A method of developing computer software, the method comprising:
maintaining a body of source code for a computer-based application;
building the computer-based application based on the body of source code; and building an annotation corresponding to the computer-based application based on information extracted from the body of source code.
maintaining a body of source code for a computer-based application;
building the computer-based application based on the body of source code; and building an annotation corresponding to the computer-based application based on information extracted from the body of source code.
41. The method of claim 40 in which the computer-based application comprises an instructional example.
42. The method of claim 40 in which the maintaining comprises including program instructions and explanatory information in the body of source code.
43. The method of claim 42 further comprising including in the body of source code symbols for distinguishing between program instructions and explanatory information.
44. The method of claim 42 further comprising including in the body of source code symbols for identifying program instructions that are to be used for building interactive examples.
45. The method of claim 42 further comprising including in the body of source code symbols that define a manner in which the explanatory information is to be presented to an end-user.
46. The method of claim 40 further comprising assembling a list of predetermined tokens appearing in the body of source code.
47. The method of claim 46 further comprising generating a link to an online reference for each token in the assembled list.
48. The method of claim 46 in which the token comprises a keyword.
49. The method of claim 46 in which the token comprises a class name.
50. The method of claim 40 further comprising including in the body of source code symbols for identifying a source code fragment that is to be presented to an end-user.
51. The method of claim 50 further comprising generating a jump that allows an end-user to access the body of source code at a location corresponding to the source code fragment.
52. The method of claim 40 in which building of the annotation comprises parsing the body of source code to identify portions of the source code that correspond to the annotation.
53. The method of claim 52 in which the parsing comprises processing the body of source code with a script that recognizes predetermined markup symbols appearing in the body of source code.
54. The method of claim 52 in which building of the annotation comprises generating documentation source files based on a result of the parsing.
55. The method of claim 54 further comprising compiling the documentation source files into a format recognized by an online help utility.
56. The method of claim 52 in which building of the annotation comprises generating example source code files based on a result of the parsing.
57. The method of claim 56 further comprising compiling the example source code files into interactive examples that can be executed by an end-user.
58. Computer software, residing on a computer readable medium, comprising:
source code from which a computer-based application can be built; and symbols within the source code designating portions of the source code from which descriptive content for providing instruction for using the computer-based application can be built.
source code from which a computer-based application can be built; and symbols within the source code designating portions of the source code from which descriptive content for providing instruction for using the computer-based application can be built.
59. A method, performed on a computer system, of instructing a user, the method comprising:
performing an instructional example;
simultaneously providing explanatory information associated with the example;
permitting user interaction with at least one of the example and the explanatory information; and maintaining synchronization between the example and the explanatory information in response to the user interaction.
performing an instructional example;
simultaneously providing explanatory information associated with the example;
permitting user interaction with at least one of the example and the explanatory information; and maintaining synchronization between the example and the explanatory information in response to the user interaction.
60. A method, performed on a computer system of educating a user about computer programming concepts, the method comprising:
allowing the user to designate a programming topic of interest;
providing the user with an annotation descriptive of the designated programming topic;
enabling the user to selectively execute an interactive example instructive of the designated concept;
displaying a result of the selectively executed interactive example; and simultaneously with execution of the interactive example, automatically updating the annotation to display information that explains the displayed result of the interactive example.
allowing the user to designate a programming topic of interest;
providing the user with an annotation descriptive of the designated programming topic;
enabling the user to selectively execute an interactive example instructive of the designated concept;
displaying a result of the selectively executed interactive example; and simultaneously with execution of the interactive example, automatically updating the annotation to display information that explains the displayed result of the interactive example.
Applications Claiming Priority (2)
| Application Number | Priority Date | Filing Date | Title |
|---|---|---|---|
| US08/888,925 | 1997-07-07 | ||
| US08/888,925 US6259445B1 (en) | 1997-07-07 | 1997-07-07 | Computer-based documentation and instruction |
Publications (1)
| Publication Number | Publication Date |
|---|---|
| CA2242408A1 true CA2242408A1 (en) | 1999-01-07 |
Family
ID=25394182
Family Applications (1)
| Application Number | Title | Priority Date | Filing Date |
|---|---|---|---|
| CA002242408A Abandoned CA2242408A1 (en) | 1997-07-07 | 1998-07-06 | Computer-based documentation and instruction |
Country Status (6)
| Country | Link |
|---|---|
| US (2) | US6259445B1 (en) |
| EP (1) | EP0890900A3 (en) |
| JP (1) | JPH11161398A (en) |
| AU (1) | AU761413B2 (en) |
| BR (1) | BR9802350A (en) |
| CA (1) | CA2242408A1 (en) |
Families Citing this family (75)
| Publication number | Priority date | Publication date | Assignee | Title |
|---|---|---|---|---|
| JP2826252B2 (en) | 1993-04-23 | 1998-11-18 | インターナショナル・ビジネス・マシーンズ・コーポレイション | Optical disk drive and signal calibration method thereof |
| US6728933B1 (en) * | 1996-11-03 | 2004-04-27 | International Business Machines Corporation | System and method for importing data |
| US7111009B1 (en) | 1997-03-14 | 2006-09-19 | Microsoft Corporation | Interactive playlist generation using annotations |
| US6026233A (en) * | 1997-05-27 | 2000-02-15 | Microsoft Corporation | Method and apparatus for presenting and selecting options to modify a programming language statement |
| US6421065B1 (en) * | 1998-02-09 | 2002-07-16 | Microsoft Corporation | Access of online information featuring automatic hide/show function |
| US6456303B1 (en) | 1998-02-09 | 2002-09-24 | Microsoft Corporation | Method and system for access of online information |
| WO2000016541A1 (en) * | 1998-09-15 | 2000-03-23 | Microsoft Corporation | Annotation creation and notification via electronic mail |
| US6956593B1 (en) * | 1998-09-15 | 2005-10-18 | Microsoft Corporation | User interface for creating, viewing and temporally positioning annotations for media content |
| US6993720B1 (en) * | 1999-05-14 | 2006-01-31 | Cnet Networks, Inc. | Apparatus and method for integrated software documentation |
| CA2293068C (en) * | 1999-12-22 | 2008-01-15 | Ibm Canada Limited-Ibm Canada Limitee | System and method for managing messages and annotations presented in a user interface |
| US6628311B1 (en) * | 2000-02-03 | 2003-09-30 | Ricoh Company, Ltd | Graphical user interface including hyperlinks in a help message dialog box |
| JP2001344203A (en) * | 2000-03-29 | 2001-12-14 | Seiko Epson Corp | Aiding method for aiding solution of abnormality of device |
| US7302490B1 (en) * | 2000-05-03 | 2007-11-27 | Microsoft Corporation | Media file format to support switching between multiple timeline-altered media streams |
| US7240297B1 (en) * | 2000-06-12 | 2007-07-03 | International Business Machines Corporation | User assistance system |
| US7086067B1 (en) | 2000-07-14 | 2006-08-01 | International Business Machines Corporation | Dynamic Java bean for VisualAge for Java |
| US6857103B1 (en) * | 2000-07-14 | 2005-02-15 | International Business Machines Corporation | Flexible help support in an object oriented application |
| US7568152B1 (en) * | 2000-07-14 | 2009-07-28 | International Business Machines Corporation | Text file interface support in an object oriented application |
| US6931385B1 (en) | 2000-09-28 | 2005-08-16 | Sumisho Computer Systems Corporation | Interactive examples for online coding tutorials |
| US6718350B1 (en) | 2000-11-21 | 2004-04-06 | Pitney Bowes Inc. | Method and system for selectively updating rating data and software data via internet or intranet in a carrier management system |
| US7913170B2 (en) * | 2000-12-20 | 2011-03-22 | National Instruments Corporation | System and method for performing type checking for hardware device nodes in a graphical program |
| US7895583B2 (en) * | 2000-12-22 | 2011-02-22 | Oracle International Corporation | Methods and apparatus for grammar-based recognition of user-interface objects in HTML applications |
| US7033179B2 (en) * | 2001-03-27 | 2006-04-25 | Schneider Automation Inc. | Web based factory automation training on demand |
| US7614014B2 (en) * | 2001-04-05 | 2009-11-03 | Daniel Keele Burgin | System and method for automated end-user support |
| US8096809B2 (en) | 2001-04-05 | 2012-01-17 | Convergys Cmg Utah, Inc. | System and method for automated end-user support |
| US20020147848A1 (en) * | 2001-04-05 | 2002-10-10 | Burgin Daniel Keele | System and method for enabling communication between browser frames |
| US7679774B2 (en) * | 2001-04-06 | 2010-03-16 | Oce Printing Systems Gmbh | Method, system and computer program for the generation of an electronic document from scanned image data |
| EP1456769A4 (en) | 2001-07-26 | 2004-11-17 | Irise Inc | System and process for gathering, recording and validating requirements for computer applications |
| EP1280070A1 (en) * | 2001-07-26 | 2003-01-29 | Hewlett-Packard Company, A Delaware Corporation | Method and computer program for generating a list of items for viewing in a browser |
| US7024658B1 (en) | 2001-09-28 | 2006-04-04 | Adobe Systems Incorporated | Extensible help facility for a computer software application |
| US8131815B1 (en) | 2001-11-02 | 2012-03-06 | Adobe Systems Incorporated | Client-side modification of electronic documents in a client-server environment |
| AU2001298079A1 (en) * | 2001-11-22 | 2003-06-10 | Liqwid Krystal India Private Limited | System and method for software learning |
| US20030131337A1 (en) * | 2002-01-07 | 2003-07-10 | Perumainar Asok K. | Educational method and tool for isolating and teaching programming language concepts |
| US6988240B2 (en) * | 2002-03-29 | 2006-01-17 | Global Knowledge, Inc. | Methods and apparatus for low overhead enhancement of web page and markup language presentations |
| US7127675B1 (en) * | 2002-07-15 | 2006-10-24 | Sprint Spectrum L.P. | Method and system for automatically revising software help documentation |
| US7797353B1 (en) * | 2002-09-13 | 2010-09-14 | Cadence Design Systems, Inc. | Method and system for enhancing software documentation and help systems |
| US20040085365A1 (en) * | 2002-11-01 | 2004-05-06 | Wulf Eggers | Technique for implementing a functionality tree for an air traffic management system |
| US7222298B2 (en) * | 2002-11-12 | 2007-05-22 | Siemens Communications, Inc. | Advanced JAVA rich text format generator |
| US7565607B2 (en) * | 2003-01-07 | 2009-07-21 | Microsoft Corporation | Automatic image capture for generating content |
| GB0303977D0 (en) * | 2003-02-21 | 2003-03-26 | Ibm | A method and system for generating a tutorial application |
| US7836401B2 (en) * | 2003-03-20 | 2010-11-16 | Siemens Medical Solutions Usa, Inc. | User operable help information system |
| US9778919B2 (en) * | 2003-06-27 | 2017-10-03 | Adobe Systems Incorporated | Dual context interaction with a content object for facilitating content creation and software development |
| US7325204B2 (en) * | 2003-08-29 | 2008-01-29 | Yahoo! Inc. | Slideout windows |
| US7395500B2 (en) * | 2003-08-29 | 2008-07-01 | Yahoo! Inc. | Space-optimizing content display |
| US7890961B2 (en) * | 2003-08-29 | 2011-02-15 | Yahoo! Inc. | Method and apparatus for providing desktop application functionality in a client/server architecture |
| US7496607B2 (en) * | 2003-08-29 | 2009-02-24 | Yahoo! Inc. | Method and system for maintaining synchronization between a local data cache and a data store |
| EP1676251A1 (en) * | 2003-10-08 | 2006-07-05 | Innerworkings (Holdings) Limited | A learning system |
| US20050166148A1 (en) * | 2004-01-28 | 2005-07-28 | Garding Phillip D. | Interactive user message system and method |
| CN100573503C (en) * | 2004-07-08 | 2009-12-23 | 微软公司 | The method and system of automatically generated content |
| US20060048063A1 (en) * | 2004-08-24 | 2006-03-02 | Sbc Knowledge Ventures, L.P. | Design request form |
| US20060069595A1 (en) * | 2004-09-30 | 2006-03-30 | International Business Machines Corporation | Business system management procedures research and analysis methodology |
| US10514816B2 (en) * | 2004-12-01 | 2019-12-24 | Uber Technologies, Inc. | Enhanced user assistance |
| US8176422B2 (en) * | 2004-11-19 | 2012-05-08 | International Business Machines Corporation | Method for aligning demonstrated user actions with existing documentation |
| WO2009002293A1 (en) * | 2005-04-29 | 2008-12-31 | Turnstyle Website Architecture | Independent data navigation within a document |
| US9026990B2 (en) * | 2005-08-16 | 2015-05-05 | International Business Machines Corporation | Dynamic filtering of a navigation path to a set of minimums |
| US7669137B2 (en) * | 2005-11-04 | 2010-02-23 | International Business Machines Corporation | Computer method and apparatus for representing a topic in a software modeling system |
| US20070260631A1 (en) * | 2006-03-09 | 2007-11-08 | Microsoft Corporation | Embedded decision support |
| US20070220429A1 (en) * | 2006-03-17 | 2007-09-20 | Microsoft Corporation | Layered customization of a help user interface |
| US8099664B2 (en) * | 2006-03-17 | 2012-01-17 | Microsoft Corporation | Dynamic help user interface control with secured customization |
| CA2543304A1 (en) * | 2006-04-11 | 2007-10-11 | Ibm Canada Limited - Ibm Canada Limitee | Code highlight and intelligent location descriptor for programming shells |
| US7954049B2 (en) | 2006-05-15 | 2011-05-31 | Microsoft Corporation | Annotating multimedia files along a timeline |
| US20070271085A1 (en) * | 2006-05-19 | 2007-11-22 | Louenas Hamdi | Emulation of an interactive electronic form |
| US20070276852A1 (en) * | 2006-05-25 | 2007-11-29 | Microsoft Corporation | Downloading portions of media files |
| US20080155412A1 (en) * | 2006-12-20 | 2008-06-26 | Microsoft Corporation | Quick reference card and on-line help for a computing system |
| US20080244401A1 (en) * | 2007-04-02 | 2008-10-02 | Microsoft Corporation | User interface teaching concepts in an application |
| US20080294448A1 (en) * | 2007-05-23 | 2008-11-27 | At&T Knowledge Ventures, Lp | Methods and systems associated with telephone directory advertisements |
| US8340492B2 (en) * | 2007-12-17 | 2012-12-25 | General Instrument Corporation | Method and system for sharing annotations in a communication network |
| US8291319B2 (en) * | 2009-08-28 | 2012-10-16 | International Business Machines Corporation | Intelligent self-enabled solution discovery |
| EP2625606A4 (en) | 2010-10-08 | 2014-11-26 | Irise | System and method for extending a visualization platform |
| JP2013016013A (en) * | 2011-07-04 | 2013-01-24 | Omron Corp | Development support device and development support method |
| DE112012007259T5 (en) | 2012-12-26 | 2015-09-24 | Mitsubishi Electric Corporation | Electronics Manual Browse Leaflet and System |
| US9733904B2 (en) * | 2013-12-12 | 2017-08-15 | Sap Se | Content-aware code fragments |
| US9965348B2 (en) | 2014-11-12 | 2018-05-08 | International Business Machines Corporation | Optimized generation of data for software problem analysis |
| EP3043259A1 (en) | 2015-01-09 | 2016-07-13 | Tata Consultancy Services Limited | Computer programs components dependencies analysis |
| US10990639B2 (en) * | 2018-10-18 | 2021-04-27 | Sap Se | Search techniques using context |
| US11314503B2 (en) | 2020-06-08 | 2022-04-26 | Bank Of America Corporation | Software development documentation using machine learning |
Family Cites Families (15)
| Publication number | Priority date | Publication date | Assignee | Title |
|---|---|---|---|---|
| US5239617A (en) | 1990-01-05 | 1993-08-24 | International Business Machines Corporation | Method and apparatus providing an intelligent help explanation paradigm paralleling computer user activity |
| US6678706B1 (en) | 1991-04-18 | 2004-01-13 | International Business Machines Corporation | Hypertext marker and method for dynamically displaying help information in an interactive data processing system |
| US5481667A (en) * | 1992-02-13 | 1996-01-02 | Microsoft Corporation | Method and system for instructing a user of a computer system how to perform application program tasks |
| JPH0644339A (en) * | 1992-03-06 | 1994-02-18 | Hewlett Packard Co <Hp> | Graphic object operation system and method |
| US5493658A (en) * | 1992-03-26 | 1996-02-20 | International Business Machines Corporation | Interactive online tutorial system with monitoring function for software products |
| US5339433A (en) * | 1992-11-19 | 1994-08-16 | Borland International, Inc. | Symbol browsing in an object-oriented development system |
| US5469540A (en) * | 1993-01-27 | 1995-11-21 | Apple Computer, Inc. | Method and apparatus for generating and displaying multiple simultaneously-active windows |
| US5485618A (en) | 1993-12-15 | 1996-01-16 | Borland International, Inc. | Methods and interface for building command expressions in a computer system |
| US5600831A (en) * | 1994-02-28 | 1997-02-04 | Lucent Technologies Inc. | Apparatus and methods for retrieving information by modifying query plan based on description of information sources |
| JPH0876955A (en) * | 1994-09-01 | 1996-03-22 | Fujitsu Ltd | System and method for displaying selection substance |
| US5678039A (en) * | 1994-09-30 | 1997-10-14 | Borland International, Inc. | System and methods for translating software into localized versions |
| US6026388A (en) * | 1995-08-16 | 2000-02-15 | Textwise, Llc | User interface and other enhancements for natural language information retrieval system and method |
| US5717879A (en) | 1995-11-03 | 1998-02-10 | Xerox Corporation | System for the capture and replay of temporal data representing collaborative activities |
| US5786815A (en) | 1996-05-31 | 1998-07-28 | Sun Microsystems, Inc. | Configurable runtime graphical user interface widget management |
| US6016467A (en) * | 1997-05-27 | 2000-01-18 | Digital Equipment Corporation | Method and apparatus for program development using a grammar-sensitive editor |
-
1997
- 1997-07-07 US US08/888,925 patent/US6259445B1/en not_active Expired - Lifetime
-
1998
- 1998-07-03 AU AU74158/98A patent/AU761413B2/en not_active Ceased
- 1998-07-06 CA CA002242408A patent/CA2242408A1/en not_active Abandoned
- 1998-07-07 BR BR9802350-0A patent/BR9802350A/en not_active IP Right Cessation
- 1998-07-07 JP JP22748798A patent/JPH11161398A/en active Pending
- 1998-07-07 EP EP98305384A patent/EP0890900A3/en not_active Withdrawn
-
1999
- 1999-01-25 US US09/236,105 patent/US6724401B1/en not_active Expired - Fee Related
Also Published As
| Publication number | Publication date |
|---|---|
| US6724401B1 (en) | 2004-04-20 |
| AU761413B2 (en) | 2003-06-05 |
| AU7415898A (en) | 1999-01-14 |
| EP0890900A2 (en) | 1999-01-13 |
| BR9802350A (en) | 1999-10-13 |
| EP0890900A3 (en) | 2000-09-27 |
| US6259445B1 (en) | 2001-07-10 |
| JPH11161398A (en) | 1999-06-18 |
Similar Documents
| Publication | Publication Date | Title |
|---|---|---|
| US6259445B1 (en) | Computer-based documentation and instruction | |
| US7490292B2 (en) | Web-based instruction | |
| Walrath | The JFC Swing tutorial: a guide to constructing GUIs | |
| US5493658A (en) | Interactive online tutorial system with monitoring function for software products | |
| d'Anjou | The Java developer's guide to Eclipse | |
| US5442759A (en) | Interactive online tutorial system with user assistance function for software products | |
| US5535422A (en) | Interactive online tutorial system for software products | |
| US20110107321A1 (en) | Editor for program files | |
| Krause | Foundations of GTK+ development | |
| Scarpino et al. | SWT/JFace in Action: GUI Design with Eclipse 3.0 | |
| Grosjean et al. | SciViews-R | |
| Olivero et al. | Enabling program comprehension through a visual object-focused development environment | |
| Kölling | Teaching object orientation with the blue environment | |
| Holzner | Visual Basic 6 Black Book | |
| Moore | Python GUI Programming with Tkinter: Design and build functional and user-friendly GUI applications | |
| Topley | Core Swing: advanced programming | |
| MXPA98005468A (en) | Documentation and instruction, based on computed | |
| Liberty et al. | Programming. NET Windows Applications | |
| Blewitt | Eclipse Plug-in Development: Beginner's Guide | |
| Oancea et al. | Visual Basic. NET by Example | |
| Foxall | Sams Teach Yourself Visual C# 2008 in 24 Hours: Complete Starter Kit | |
| McGrath | Visual Basic in easy steps | |
| Wang | Mac Programming for Absolute Beginners | |
| Feiler | Sams Teach Yourself Core Data for Mac and IOS in 24 Hours | |
| Mueller | Start Here! Learn Microsoft Visual C# 2010 |
Legal Events
| Date | Code | Title | Description |
|---|---|---|---|
| EEER | Examination request | ||
| FZDE | Discontinued |