To document a tool or toolbox, you edit the Description page as described below.
Editing a Description page
There are different ways to access the Description page of a tool or toolbox.
In the Catalog window
- Right-click a tool or toolbox you created and click Item Description. This will open the Item Description window, displaying the Description page.
- Click the Edit button
.
In ArcCatalog
- In the Catalog tree view, select a tool or toolbox you created.
- In the contents panel, click the Description tab.
- Click the Edit button .
In the Search window
When a tool or toolbox is found as the result of your search in the Search window, as described in A quick tour of finding tools, you can access its Description page as follows:
- Hover the pointer over the tool or toolbox name; a pop-up window appears with a link to Item Description at the bottom. Click that link to open the Item Description window, then click the Edit button .
- Click the summary line of the tool or toolbox found below its name to open the Item Description window, then click the Edit button .
Entering a tool's description
The Description page of a tool also uses a standard template provided by ArcGIS, structured the same as a system tool reference page. Initially, this page is empty, showing only the default content, such as the tool name, parameter names, and parameter data types. You need to fill in the relevant information, following the tips given at the bottom of the editor, in these areas:
- Title: You can type in a different and perhaps more descriptive title for your tool. This alternative title will be displayed on the Item Description page.
- Thumbnail: You can browse to an image file (such as a .jpg or .png) that illustrates what the tool does. It is recommended that the width of the graphic not exceed 600 pixels—if larger, the graphic may be cut off when printed.
- Tags: You can enter words that are used to identify the subject of your tool in the system.
- Summary: You can write a short summary about what your tool does.
- Usage: You can enter one or more tips that are important for your users to know.
- Syntax: The tool syntax defines the tool parameters and how they affect the results of the tool. Although the parameter names and types are automatically populated in the table, you need to enter these parameter explanations:
- The Dialog explanation is the reference for a parameter on the tool dialog box. This reference is displayed in the side panel of a tool dialog box when you click Show Help.
- The Scripting explanation is the reference for the same parameter used in scripting. This reference is displayed on the Item Description page and the Help section of the Python window.
- Code Samples: You can provide one or more samples of Python code that demonstrate how your tool is used in Python. For each example, you can provide a title, a description of the example, and the Python code.
- Tool sidebar help image: This is an image that appears in the side-panel help for the tool. It is recommended that the width of the graphic not exceed 400 pixels.
- Credits: You can acknowledge people or organizations who contributed to the tool design and implementation.
Entering a toolbox description
The description page of a toolbox uses a standard template provided by ArcGIS. Initially, this page is empty, showing only the default content, such as the toolbox name and the toolsets in it. You need to fill in the relevant information, following the tips given at the bottom of the editor, in these areas:
- Title: You can type in a different and perhaps more descriptive title for your toolbox. This alternative title will be displayed on the Description page.
- Thumbnail: You can browse to an image file (such as a .jpg or .png) that illustrates what the toolbox contains.
- Tags: You can enter words that are used to identify the subject or content of your toolbox in the system.
- Summary: You can write a short summary about what is in the toolbox.
- Description: You can write a more detailed explanation about your toolbox.
- Credits: You can acknowledge people or organizations who contributed to the resources.
Item Description is used in search
The documentation you provide in the Item Description is used by the Search window to find your tool. The next time Search indexes your tools, the summary and keywords are parsed and added to the search index.