Documenting Programs

1. Introduction

Scripts really cannot stand on their own. Even if you provide a tool for ArcGIS, users need to know what it does and how to install it as they may never have installed a tool before. If the script is a command-line script, you'll need to let users know what it does and how to pass parameters to it. As command-line scripts can take days to run and can create thousands of files, you'll want to give them some instruction up front.

You have already spent a great a great deal of time trying to decipher others documentation (including the documentation for this class). Think about what worked for you and what did not. Always remember these early and frustrating experiences as you are now the developer providing tools to others - don't be the person that creates scripts no one can use!

There are a couple of simple approaches to providing documentation for scripts. These include ReadMe.txt files and providing HTML files. Either of these files can be added to the folder the script is delivered in and the formats are almost always supported on every computer.

Any ReadMe file should have the following contents:

• Purpose of the script
• Intellectual Property Rights (either open source license or the person/organization owning the copyright)
• Installation instructions
• Getting started instructions (how to start using the tools)
• Anything else the might need!
• Who to contact if there is problem

2. ReadMe Files

You've probably already seen a "ReadMe.txt" file in a folder somewhere on your computer. These are simple text files that give the user some idea of what is going on. Since they are text files they use simple lines of characters similar to the lines of pound signs you've used in your scripts for formatting. Remember to provide the user with all the information they need in an easy to read format.

3. HTML Files

Almost everyone has a browser on their computer these days so it's becoming common to see a "ReadMe.html" or a "Install.html" in a folder with a tool. There can also be a folder called something like "Documentation" that includes an entire website for the tool. You can just click on the HTML files to view them in a browser. Within HTML you have a great deal of flexibility on how the page is structured. Make sure to make clear sections with all the information the user might need. Only use standard HTML tags and commonly supported image types (PNG and JPEG).