Help with documentation

Hi. I’m relatively new to Applescripting “ I started about three months ago “ and I’ve managed to create an absolute monster of a script. It takes an Excel spreadsheet, runs the data through an Excel template that sorts it into several CSV files, edits the CSV files to get rid of a few consistent problems, and then runs each of those files through a second set of spreadsheets which tag the data with Xpress tags. It then imports the tagged files into Quark 6 templates, exports each page of those as an individually named EPS and converts those files into PDFs which are sorted by two criteria. It’s long and complicated, and to the untrained eye quite scary.

The thing is, I need to be able to hand over the script to other people “ quite possibly people with little or no experience of Applescript but at least with a basic understanding of the principles of programming. I’m trying to write a document that would help someone understand what the script does and pinpoint which parts they would need to edit if anything changed. Does anyone have any useful advice, and are there any things you would expect from that sort of document?

Thanks in advance,

Handing maintenance over to someone else is always a difficult thing to do smoothly. My focus would be on making the code as readable as possible.

Part of this is consistency of style, but the part I like to focus the most on is making small chunks of code (handlers are a must) that use descriptive names that read fairly well. Sometimes this means tearing out a gnarly piece of code and putting it into its own handler so you can replace a that big chunk of code with a simple call to a handler with a nice descriptive name.

Descriptive names are useful for variables, too. Any significant variable should also have a descriptive name. Short variable names like i, o, etc. are usually OK for temporary use in very simple contexts, but I try to avoid them in more complicated situations. The classical progression of nested loop variables from i to j to k is cute, but unless the loops are processing something like a multiple-dimension array, they are not terribly descriptive names.

There is a quote from Structure and Interpretation of Computer Programs related to all this that I like very much:

If things are still not clear enough after making the code as readable as possible (sometimes there are things like performance constraints that prevent structuring the code in the most readable way), then some documentation might be useful.

Assumptions are always good things to document. Both the small assumptions and the large assumptions are important to document. The small assumptions that pieces of code make are things like “the list will never be empty”, and “because of the above if statement, we know the extension will always be png”. The large assumptions that scripts or applications make are things like “the work directory will contain only the files that need to be processed”, “all images will be png format”, “requires Mac OS X 10.5 due to .”, and “developed and tested only on Mac OS X 10.4.11 with Mail 2.1.2 and Address Book 4.0”.

Also, the overall flow of the program and its objectives are also good to document.

Once the code is readable and the documentation is ready, it would be a good idea to have one of the people that might have to modify the program later read through it and give you feedback on any parts that were not clear. Sometimes it is not possible (the person has not been identified or hired yet, etc.), try to get at least one “third party” to review the code and documentation. It is best when the reader has similar skills and experience to the people you think might have to do the work in the future, but anyone that is not the original author can bring a valuable, fresh perspective to the review.

I have developed workflows for graphics professionals and various printing industries for the past 10+ years so I understand what you’re wanting to do. Let me say, “Don’t do it!” :cool:

I realize you are new to AS but putting your open code in others hands will elicit two responses. 1. People will misinterpret or misunderstand the instructions and break something that you’ll have to fix. Count the number of times you see a sheepish look and hear a “I don’t remember what I did. All I know is that it’s not working now.”, and 2) The people who don’t care to know how it works will ignore your instruction and your documentation and bug you to come fix it. Later on you’ll also find a number of people who just stop using it because “it broke” but don’t bother to tell you! (When this happens go immediately to the boss to get this straightened out! Trust me on this. I had a Pagemaker script that I thought everyone was running for almost 2 years. When we converted to InDesign we had a ton of conversion issues with linked graphics. Oddly, my documents converted beautifully. When the boss asked about running the script we found out they had quit using it because it “didn’t look like it was doing anything, so we stopped using it 2 years ago.” !!!)

You wrote: other people “ quite possibly people with little or no experience of Applescript but at least with a basic understanding of the principles of programming. After 22 years in Graphic Arts I’ve met less than 10 “production people” who qualify. It is up to you to write for the lowest common denominator (what that is is up to you (and your boss if they’re involved).) YOU have to plan for people to do dumb things. YOU have to plan for servers to be disconnected. YOU have to plan for someone saving an EPS with JPEG encoding and Include Transfer Functions On instead of Binary and No Transfer Functions. YOU are responsible for the edits. when things change (and they will). >> If things in your script break when conditions change, YOU need to error trap for them and make your script more flexible. (Have you tried this on another machine than your own already? That’s an early mistake people make and the first place an inflexible script usually breaks.)

Looking at your project a few things come to mind:

  • Do you need Excel? Could your data come from wherever as a delimited file that could be read directly through AS?
  • What if you upgrade to Quark 7? Could this break your script? What if one user has Quark 7 but the others have 6? Will your script allow for this?
  • Do you have default source and destination folders? What if someone deletes them? Do you want the user to retype a folder name (an incredibly common place to break a script is from users typing data)?
    • Is it on a server? Do you validate the server being mounted? If not, how does the user login?
      • (If you forced them to login with a dialog). People are whining that they have to type their password in to mount the server. Does your company’s security policy allow for human readable login info to be used this way?
-  What if there's an error in the workflow?? Does the script just stop? Or does it log the errors (if non-fatal) and continue on??

Sorry if I seem heavy-handed but I do this for a living and, despite the fact that it appears I’m reading on the Internet or just staring at words all day, writing a public script IS NOT easy! I usually write a core and work with it for several weeks at least. Integrate it into a process and see where it breaks or where it’s uncomfortable / inefficient / provides no real gain. Tweaking and rewriting as I go. Then I pick a guinea pig out of the group to beta test (someone who WILL report and be constructive). If it’s not breaking or in need of feature changes I let them run with it for a week or two. Then I write out a Standard Operating Procedure (SOP) with screencaps and everything and submit this to the person in charge for proofreading and/or sign off. Then release it to the wild and listen for the reactions. YOU need to test and fix (and have your beta tester test and you fix) to air out as many bugs as you can. (I actually have a LARGE project that is being written as AS modules that I’ve been working on for over 2 years.) Granted something always needs tweaking but should should strive for the most error-free code possible at 1.0 release.

Good luck with your project. This kind of stuff is fun in AS. I had to write a Quark EPS generator at my last job and not only did I have it watching folders (and their subfolders) but it would reboot itself around 3:00 am (it waited until the current job (if any) was done) to flush the temporary fonts in Suitcase (which can create instability after loaded 100 documents or more). Once I started it up it ran unattended for over 8 months (when we upgraded the machine) then ran on after that. It was very cool!

Jim Neumann