Do you use a proven workflow to edit and document ArcGIS ModelBuilder models?

Question

Do you have any reference to best practice examples , or can you share your expertise on how to keep track of edits to ModelBuilder models , track changes between model/tool versions and maintain model stability, robustness and function?

I am aware of the ESRI guidance to managing, copying and naming models here.

I would be interested if anyone has established practices, or specific expertise in the use of version tracking, archiving, editing of ModelBuilder tools that they successfully use to track model development and checking and to maintain models in a stable condition.

Answer 1

Currently we just keep toolboxes on a Windows file server and roll back using the "Previous Versions" functionality if anything breaks.

I am looking into storing toolboxes in Git (using TortoiseGit and GitHub Enterprise), which we already use for Python scripts and FME workspaces. Since regular toolboxes are binary, you aren't able to diff and interactively merge them like you would with plain text files, but you can still get commit messages/history, tags, branches, and merge entire binary files (all or nothing).

The best thing I think you could do would be to move over to Python completely and use Python toolboxes and Python add-ins instead of ModelBuilder. Also if you have FME that can do just about anything you can do with ModelBuilder and usually much more efficiently and easily, and is more self-documenting, with bookmarks, annotations, workspace descriptions, etc.

With GitHub you can use its Wiki or Pages features for more extensive documentation.

A more low-tech but still effective method is to simply include a readme text file with information about the toolbox/model's purpose, usage and history.

Answer 2

I don't think there is any way of tracking change in a model as you build it and I'm not sure why you would want to do that anyway?

What is important is explaining to others the reasoning behind your model. For example why do your inputs need to be in a file geodatabase, why did you create a field and divide a value by some other number?

This sort of important information is critical for users and the developer who has to pick it up when you "get run over by a bus". :)

There are two places I would document a model, as labels in model builder (these would be directed to developers) and within the item description (metadata) of the tool. You can really go to town on adding useful information which guides a user.

Unfortunately most people who develop models do a poor job on adding information to parameters which makes the model difficult to understand if you come back to it months later. I know this...I've done it!

A few minutes spent now adding some descriptions to a model parameter can turn a useful model into a great tool which is adopted rapidly by an organisation, otherwise its just another half arsed model that quickly disappears on your network drive!

Answer 3

Beside what have already been said, I would suggest to try to store your toolbox in an ArcSDE database. It can really help for concurrent edition and access. I also backup this database so I can roll back in case of a problem.

For more details, have a look at another of my answer's.

Answer 4

On the "documenting" part, use the metadata a.k.a. Item Description editor, see A quick tour of documenting tools and toolboxes.

The rich text editor box is functional but limited. Save and check the results often in both the Item Description preview and the tool dialog itself as some formatting can be jumbled or not retained, particularly list items. You can paste from Word, Onenote, Dream Weaver, etc. to get a quick start but unless the formatting is really simple it will get messed up in a hurry.

(A caveat: The old way was to use the "Model >> Edit >> Model Properties" dialog and paste in html code in the "Description" field. If you do or have done this, when Item Description editor is access the content is copied over, which is great. However any edits you make will not be copied back, so delete the model properties version to avoid confusion.)

Version control is possible by going out of the box a little: when viewing the Item Description bring up the context menu r-click >> View source and then save the html in your source-control/docs folder. Images are left out, but if you care to add yet a bit more work you can examine the html and fetch them from %temp%.

---

You might get a greater degree of control by referencing a compiled help (CHM) file. The place to start seems to be Microsoft HTML Help 1.4.