Documenting Workflows

The obvious outcomes of your geoprocessing workflow are databases with new datasets and toolboxes with new models and script tools. However, there is an important final step to your geoprocessing workflow—documentation.

Documentation is about communication and explanation. A GIS project can be a complicated and lengthy undertaking, and it might be tempting to skip the documentation step. However, all of your hard work is made much more valuable when you take the time to explain the tools, procedures, and methodology you used.

Documentation is the important final step of your geoprocessing workflow.

Documentation for geoprocessing

When you've completed your geographic analysis, it's important to be able to explain the process by which data and custom tools were created as well as the reasoning behind your methodology. Your models and script tools should have accompanying instructions explaining what they do and what purpose they serve.

The ArcGIS geoprocessing framework includes functionality for keeping a record of geoprocessing tasks and documenting your work. Once you discover these tools and learn how you can take advantage of them you will be ready to share your work with others.

Throughout this course you have been working through a project to define habitat for the Canada lynx in northeastern Washington. In the exercises in this topic you will create different types of documentation for the tools you worked with in previous parts of this lab.

Why is documentation important?

Documentation serves a number of functions. It can:

· Act as a reminder. If you want to revisit former work you've done, documentation will help you recall the reasons for the choices you made. If you make it a point to create documentation as you work through a lengthy project, it can help you recall what you've done so far and resume where you left off.

· Communicate with others. If your models and script tools are well-documented, it should be no problem for others to use them successfully. If they don't know how to use a tool, what exactly it does, or why a particular process is used, they may not be able to take advantage of the work you've done.

· Validate your work. Without adequate documentation to describe why you chose the methods and parameter values that you did, it may be difficult to convince others of your study's legitimacy.

Types of documentation

With ArcGIS, there are several methods for documenting your custom models and script tools. You can:

· Generate a report from a model. A report describes the variables, processes, and current state of your model.

· Add labels to your model diagram. Model labels serve as visual reminders or notes explaining how your model works.

· Create metadata for any custom tool. Metadata describes what the tool does, who created it, keywords, and any constraints for using the tool.

· Build help for any custom tool, to teach others and to remind yourself how it works.

In addition to documentation that you create, ArcGIS will automatically record a history of your geoprocessing operations if you choose to log them to a history model. Recall that history models are saved in the History toolbox, located in the My Toolboxes folder.

Adding a description to your custom tool's properties can also be considered a simple form of documentation.

Metadata and help for custom tools

You've seen how easy it is to generate a geoprocessing report and add labels to models. The other two forms of documentation—metadata and help—are created using the ArcToolbox™ Documentation Editor. Once you get familiar with the editing environment, you'll find that creating metadata and help for your models and script tools is also an easy task.

The Documentation Editor is divided into two sections: General Information and Help.

General Information
The General Information section is where you briefly describe the tool and provide keywords, author information, and use constraints. What you enter here can be viewed by selecting the tool in the Catalog Tree and viewing its metadata.

General Information
Section	Description
Abstract	The abstract is a short paragraph that describes the function of the tool. The abstract will appear in the tool's metadata and in the help panel when you run the tool as a dialog.
Keywords	Keywords are used for finding your tools. As long as the tools have been added to ArcToolbox, you can use the Search function to locate the tools based on keywords.
Author	The author section is where you take ownership of your work. Information that you provide here will make it easier for those who have received your tools to contact you.
Constraints	Constraints are restrictions you wish to specify about your tools. They might include copyright information, distribution limitations, the proper use of the tool, or a disclaimer.

Help
The information that you enter in the Help section populates two locations: the quick reference guidelines that can be viewed from the help panel of a tool's dialog, and the comprehensive help page that can be launched from the tool's dialog or accessed by right-clicking the tool in ArcToolbox and choosing Help.

Help
Section	Description
Summary	A summary is a more detailed description of your tool. It can be similar to or the same as the abstract in the General Information section, but here you are able to create paragraphs, bulleted lists, subsections, and hyperlinks.
Illustration	You can choose to include a graphic that describes your custom tool.
Usage Tips	Usage tips can include reasons why you would use the tool as well as important restrictions.
Parameters	There are two sections for each parameter. The Dialog Reference is for specifying what appears in the help panel of a tool's dialog. To view this text, select the parameter's text box in the dialog. The Command Reference appears on the tool's help page. If you have an entry in the Command Reference but not the Dialog Reference (or visa versa) the other will appear in its place.
Command Example	Contains sample code for running the tool at the command line.
Script Example	Contains sample code for including the tool in a script.

Sharing your work

Sharing your project data and tools usually falls into one or more of the following categories:

Sharing the results
You can share only the results of your analysis, such as maps, reports, and final data. These types of products are usually designed for specific audiences.

Sharing the procedures
You may want people to review your procedures. Sharing procedures usually means that you're inviting feedback and criticism, which is used to improve your analysis.

Sharing the tools
You can share your models and script tools so that others can run the tools with your data or adapt the tools to their own projects if possible.

For your projects, there may be an audience for each of these categories and you might have to decide on several methods for sharing your work. This short topic offers some basic guidelines you should follow when distributing geoprocessing tools and data.

Considerations for sharing your work

To share your work, you must decide on one or more delivery methods. For example, you can simply deliver a presentation, either live or over the Web; make the tools and data accessible through your organization's network; download the project files and folders to a CD and distribute it; or archive the project in a compressed file that people can download.

The following table outlines some guidelines you should consider for each method. The guidelines are described below the table.

Delivery method	Organization	Relative path	File permissions	Documentation	License issues
Live presentation
Web presentation
Network access
CD or DVD
Archive (ZIP, TAR or CAB)

· Keep your project data and tools organized in a geodatabase or logical file structure.

· Setting relative paths enables others to use your custom tools. If absolute paths are saved, the model or script will look for its inputs in the wrong locations—in the folders on the model creator's computer or network where the inputs were stored when the custom tool was created.

· Setting file permissions lets you protect folders or files that you don't want changed. You haven't done this in the course but you can use your file manager to enforce different permissions for folders and files.

· Document your custom tools with labels, metadata, and help. You learned how to do this in the previous topic.

· Be aware of ArcGIS licensing issues. Others won't be able to run models or scripts that contain geoprocessing tools they don't have a license for. Consult the Geoprocessing Commands Quick Reference Guide for more information.

Review

Documentation—supporting information for data and tools—is an important step in your geoprocessing workflow. The purpose of documenting your custom tools is to explain what they are and how they are used.

Even if you do not plan to share your tools, it is important to document them because the documentation you create will serve as a reminder of what you have built and save you time when you return to it.

There are four primary ways of documenting your geoprocessing work. You can:

· generate reports of the models you create

· annotate your models with labels

· create metadata for custom tools

· create help for custom tools

There are two forms of help documentation: the guidelines that display in the help panel of a tool's dialog, or the comprehensive help page that includes additional explanations, such as command line and scripting syntax.

To create metadata and help for custom tools, you use the ArcToolbox Documentation Editor. To populate the help page field for a specific process within a model, you use the process help editor that is accessed from ModelBuilder.