Does Your FileMaker Documentation Say Customer Service

Documentation As A Basic User Need

Apply the Tesco rule; Every little helps!

In the last twelve months one of the improvement points I decided to make in my own development was the documentation aspect. I’m not talking about user manuals or instruction books, I’m talking about documentation at the point of use.

In fields, scripts, custom functions, comment boxes, commenting within fields – essentially just about anywhere that a client would look when they are either dabbling (read: creating future work) or when a client is extending their solution themselves. What! let clients mess about with the solution – I hear some of you say…

Sometimes a client expressly asks us to develop a solution, or extend their current solution on this premise, that they will do some of the work themselves. I think it’s important to be able to know exactly what elements are for, or what they do – and even more so with critical functionality. It’s also a good thing for me as the developer, because often when you haven’t touched a solution for a few months – you sometimes forget what some of the stuff you wrote yourself does.

Documentation As A Developer Tool

Another aspect of documentation is when I pick up an existing file from a client, and I need to dissect it to find out what’s doing what and where, so leaving a documentation trail always helps there too. Things like commenting in field by using comment blocks or a double forward slash (//write a comment..). Using the comment field associated with a field in the database management window, and just about everywhere else. I’ve often had good feedback about this particular aspect, and even more so recently since I upped the ante with my point of use documentation.

The crux of this post is really to get beginners to think about leaving that documentation trail throughout the solution so that anybody picking up the file can orient themselves with it quickly. Start making a habit of good documentation, especially if you like your spangly tricks – you know, the ones that take an eternity to figure out what it does – be courteous and leave the notes and guidance that you would want yourself.

Documentation As A Witness Of Your Problem Solving Thinking

Another good reason why you should leave documentation everywhere, especially as a beginner, is that it enables me to see what you were trying to achieve, and more importantly – how you were trying to achieve it. This allows me to gain insight into how you were thinking about the problem, and therefore helps me train you to solve the problem correctly.

Here’s a selection documentation, I’m not saying what I do is best practice, nor that it’s better than anyone else’s, I’m just showing what I do – and if anybody has better or more structured way of doing things – I’m all ears.

Script documentation

Documenting scripts is probably the most commonly overlooked aspect of point-of-use documentation. Even some seasoned, highly commendable developers don’t do it, or at least not nearly enough. Matt Petrowsky, if you’ve ever watched his videos, you will see a top rate documentation process that he uses. I don’t go quite that far, but I always make sure that the basic and critical aspects are clearly documented.

document both the functionality, and critical steps (click to enlarge)

As you will see from the above image, just a couple of lines of commenting can make a big difference to a stranger picking up the file. One thing you should think of is the other person, you don’t know who they will be, so try to write in plain English and wherever possible – jargon free. Oh, and please don’t make up your own words, if you don’t know what the correct terminology is, write it out long.

documenting the key steps help visualise critical functionality

But, that’s not the only method for documenting scripts. I also document key steps using commenting within the script steps themselves. You will see in the above image that the set variable script steps are clearly documented to show the dabbler what is happening.

Warn of consequences - no documentation means no warning, but means big consequence!

You can also add warnings to your scripts too! (obviously, this one is a joke, but you get the message..)

The upshot is, no matter how much documentation that you insert, there is always room for a dabbler to fire off a script or use a portable script in the wrong way somehow, hopefully you try to error catch within your scripts, but there’s often the unforeseen, the one that got away, the loose canon – you know. (Execute Plan B!)

But, great documentation gives you a platform from which you can instantly re-train someone – you open up the file and say “look at the instructions, here, next time – read ‘em” (..or else Plan B..)

Custom Functions documentation

This is perhaps an area where I could still improve, although when you dowload some custom functions you will see for yourself that many developers – well, they like to code, writing instructions – huh! who needs those, it’ll work just fine – just use it, man….. Err, no, don’t just use it, man. Even if the guru of guru’s gives you a custom function – you check it yourself, you strip it down, you document it (inside the function) and then you use it.

This is a typical example of what I do. If you want to see some really good examples, take a look at some of the functions that Fabrice Nordman has written on FMCustomFunctions.com – like Petrowsky, he’s got it down to a fine art.

Clearly define what the function does, and what critical steps do

Since I believe that my documenation is sufficient for most dabblers, I don’t often do more than this. Feedback is welcomed.

Also notice that apart from the commented block, which has the bulk of intructions, that I also comment some of the key aspects of the function itself. You will develop your own style as you go, the important thing is to start now. Deployment of some things with FileMaker you should  wait until you have a firm grasp of, like naming conventions, but others just need you to do it from day one. This is a day one thing.

Field documentation

Fields are the things that you and anyone that touches your solution will touch the most. Ctrl+Shift+D (I can hit that in my sleep). And, you should always document fields, moreso fields that could be misconstrued. Obviously, a field called: Date, when there is only one date in the table doesn’t need much explanation, but if there’s a whole series of dates, and you’ve got one of those wonky naming conventions then you better start typing out the documentation – remember, no made up words.

Documentation of fields at the table level

Document fields clearly, they are the most touched aspect of any database

Documentation within the fields itself

Document within fields also wherever anything is critical, or is not intuitive by itself

The examples above show some of the documentation that I use in fields. I’m particularly fond of the comment box that is attached to a field. You can even access this in FileMaker, which I ocassionally do to pull a tooltip, or something like that.

Using the built in functionality can often provide a double benefit

Using the Field Comment for tooltips

Not always useful, but ocassionally very useful.

Value Lists documentation

This one is quite simple, and I pick and choose where I use this based on the client’s level of intuition/knowledge. Below is a simple demonstration of how you can break up the value list listing window to group value lists together. I’m sure there other developers that have better/different ways of doing this. I’d be glad to hear about those.

Depending on the level of capability of users, i.e. to not adjust the wrong value list

Relationship Graph documentation

I have seen some pretty dramatic documentation on the relationship graph over the years, from the sublime to the ridiculuous. I have a relatively laid back approach to the relationship graph. If there is one place that you really don’t want people messing around, yep, it’s in yer TOG’s.

Hence, I lightly pepper the RG with notes, I mean, nothing’s going to stop a militant dabbler, fortunately there aren’t too many of them – and when there are, make sure the backups are freely flowing.

Militant dabblers, plan B ‘em all the way to the parking lot, then plan B ‘em some more, I say

I hope you gain something from this post, I certainly hope it makes you think about the level of documentation that you are currently employing.

Stay tuned, and leave me a comment below, now.

About the Author: Darren Lunn used to be a documentation no-do-gooder, but in recent times has dramatically improved. An is righting en arf improved You can connect with Darren on Twitter

No related posts.

Tagged as: Basic Techniques, Communication, Learning FileMaker, Organising Data