A quick tour of documenting tools and toolboxes

To document a tool or toolbox, you edit the Description page as described below.

Note:

Toolsets do not have an item description, and you cannot enter documentation for toolsets.

Editing aDescription page

There are different ways to access the Description page of a tool or toolbox.

In the Catalog window or ArcCatalog

• 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 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 do one of the following to access its Description page:

• Hover over the tool or toolbox name; a pop-up window will appear 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 below its name to open the Item Description window, then click the Edit button .

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 resource(s).

Entering tool 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.
  Note:

  The image is only displayed in the item description and not in the tool's side-panel help.

• 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.
  For most parameters, the dialog box explanation and the scripting explanation are the same. But for certain parameters, such as a check box on a dialog box (a Boolean with keywords in scripting) or a multiple input field on the dialog box (a multivalue parameter in scripting), you may need to explain them differently, telling how a user interacts with the dialog box controls and specifies keywords or values in scripting.
• Code Samples: You can provide examples of Python code that demonstrate how your tool is used in the Python window and how it is used in a stand-alone script. For each example, you can provide a title, a description of the example, and the Python code.
• Credits: You can acknowledge people or organizations who contributed to the tool design and implementation.

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.

Learn more about ArcGIS Search and indexing