Technical Tips
NOTE: Assumes a practical understanding of ArcGIS model builder
ArcGIS provides the user with a powerful capability to extending the base geoprocessing toolset with the ability to create new toolsets that can be combinations of geoprocessing models or scripts. Our previous technical tip (December 2007) described two methods for documenting geoprocessing models. This technical tip is focused on how to build user HELP.
Most end-users create tools (models and/or scripts) to:
• Increase efficiency by removing the need to remember complex geoprocessing steps
• Increase efficiency and knowledge dissemination by providing a mechanism to share corporate knowledge amongst staff
• Increase reliability and transparency by providing a means to easily repeat key geoprocessing operations.
For the purpose of explaining this tip we will be using an ArcGIS geoprocessing model developed by Spatial Vision to undertake slope classification and analysis for commercial forest applications. A Model is a geoprocessing concept that uses inputs (datasets) and functions (geoprocessing action on the dataset(s) to produce outputs (datasets). In addition models allow for parameters related to geoprocessing function or input datasets to be used as variables. The inputs, outputs, function and parameters are all model objects that can be manipulated by the end user.
As discussed last time, it is possible to print the model (a set of geoprocessing objects and actions) and store this information as hardcopy or PDF however there are more sophisticated options available to communicate this information. The last tip talked about methods to enhance the visual representation of models and to use Toolbox Documentation Editor to create User Guides or Technical Guides or Command Reference Help.
Figure 1 - Right-click on the tool to be documented and select Edit Documentation to begin the ArcToolbox Documentation Editor.
An additional option for documentation is the provision of HTML-help that can be created by the Documentation Editor. The HTML-help is accessed by right-click on the tool and selecting Help or via the Parameter View in the top left-hand corner of the User Guide Panel. The Help section of the Documentation Editor is made up of six sections.
Figure 2 -Information entered into the Summary appears in the HELP at the beginning of the HTML page.
Options for documentation of a Tool
The following section describes what can be achieved in terms of documentation of a tool.
There are 5 key options that will appear in Summary, Usage Tips and Parameters sections of the documentation editor. These are described below.
Illustration
A useful addition to any documentation (particular where the model or process is complex) is to provide an illustration or diagram. The ArcGIS help editor allows you to add as many illustrations as required to visualise your process.
Illustrations or diagrams can be in created in any way you choose, however it is worth noting that you are able to export the Visual Mode of the model you have created by opening the model to EDIT and clicking on the Export-To Graphic option in the edit menu.
Figure 3 -Adding an illustration to the Help for a tool.
Usage Tips
Usage Tips are a common way to provide short messages to your audience as to either how to use the tool or things to look out for when using the tool. These appear after the illustration (if provided). Short statements in the form of bullet points are recommended.
Figure 4 -The example below provides an illustration of a usage tip consisting of an introduction and a set of bullet points followed by an additional diagram.
Parameters
The majority of models you will develop will have at least one parameter of variable. A short summary of what the parameter is and its function in the model is useful to a third party in understanding your model. The defined parameters of your model are perhaps the most important part of the documentation process from the user's perspective. It is these parameters or variables that the user interacts with.
Figure 5 -An example of adding information about parameters to appear in both the HTML-Help and User Guide Panel.
The ArcToolbox Documentation Editor will dynamically add your parameter list into the interface for you to document. Under each parameter heading there will be two documentation options:
• Command Reference - information in this section will appear in the HTML-Help for the tool
• Dialogue Reference - information in this section will appear in the User Guide Panel for the tool
The same documentation concept described for the Summary and User Tips section apply to this section. The level of detail is optional but as a minimum, at least one paragraph in the Command and Dialogue reference should be added - as a general rule we use the same paragraph for both areas.
Command Example
This HELP option allows you to add an example of how the tool might be used in a command line mode or more importantly as part of a script (python) or program for automation. This option is particularly useful in cases where you have developed python scripts that have a set of inputs (parameters) or arguments.
However, in most models developed, this part of the HELP can be ignored as this level of documentation is generally reserved for more complex, modular or integrated models or scripts.
Figure 6 -The editor allows you to add the command line or script syntax for the user.
Script Example
This section of the HELP allows you to add an example of how the tool you have developed could be used in a python script - that is an example application of the tool. Generally this will only be relevant for tools that have been designed as modules that can be used or called from other tools or scripts or for tools that have been developed directly in python or VB.
The result of adding documentation is that the information can be accessed via HTML in a structured format.
Figure 7 -A script example can be added to the editor by copy and pasting the python or VB from a text editor.
Figure 8 - The HTML-help that is created from the information put into the Editor.
Process Documentation
In addition to documentation of parameters, the Editor can also document the geoprocessing functions that you have used in your model.
Figure 9 -Open the model in EDIT or Visual Mode and Right-Click on a Yellow Geoprocess and select Edit Documentation.
To edit the key processes in your tool for technical reference, first open (edit) the tool in Visual Mode, select the process that you wish to document and right-click and select Edit Documentation.
The dialogue that results (with similar tools from the general editing process) enables you to document each process in your tool. This information will appear in the HTML-help for the tool.
Documentation Results
User Guide Panel
As a result of entering information into the Documentation Editor, the User Guide Panel will now display any information that is linked to the model parameters.
Figure 10a&b - The results of documentation in the Parameter View.
Figure 10a - The summary information will appear in the User Guide Panel.
Figure 10b - Clicking into a parameter provides information about that parameter.
HTML-help
As well as the User Guide Panel, documentation on the tool can be accessed in a HTML format. This information can be accessed in two ways:
(1) Right-click on the tool and select the Help option.
(2) Click on the Help icon in the top left-hand corner of the User Guide Panel.
The HTML-help is generated from the information put into the editor. This information is formatted into a structured HTML page. The page is a temporary file and is re-generated each time you access the Help.
Figure 11 - The results of documentation in HTML format.
Reporting on Model Settings
Each geoprocessing object in any model created in Model Builder has specific settings for any particular run. Parameters allow the user to change setting but at all times each object has a specific setting. An important documentation function for many project is to record the specific instance of a model. ArcGIS allows this via the Model Report function available in the View Mode.
To access this function open the model in View Mode click on the Model Menu and select Report.
Figure 12a&b - Creating a report on the settings for a model.
Figure 12a
Figure 12b
Summary
In summary the integration of the HELP capability with the general tool documentation significantly enhances the ability to create tools that are well documented for internal and external use. These capabilities, like the XML metadata capability of ArcGIS, assist to ensure an organisation's corporate knowledge represented by tools, models and processes developed in Model Builder is captured and distributed.
back to top
Copyright © Spatial Vision, Monday, 17-March-2008 |
