Gamasutra: The Art & Business of Making Gamesspacer
Swiss Army Chainsaw: A Common Sense Approach to Tool Development
View All     RSS
June 26, 2017
arrowPress Releases
June 26, 2017
Games Press
View All     RSS






If you enjoy reading this site, you might also want to check out these UBM Tech sites:


 
Swiss Army Chainsaw: A Common Sense Approach to Tool Development

September 21, 2006 Article Start Previous Page 4 of 5 Next
 

It's All Gone Pear-Shaped

When something goes wrong, users don't really care what went wrong, or why. All they really want to know is how to fix it as quickly as possible so they can get on with whatever it is they do.

Your error messages should be designed to be helpful to the user, not to you. You've got a debugger, they don't. Try and phrase them in such a way that they will help a user figure out how to fix things. Consider linking the error to a separate helpfile with more information. If you've got a wiki, create a page for each error, and add a button your error dialog which pops up a browser. Give each error message a unique code to aid linking (eg "ERR015 - mesh has non-manifold geometry").

Batch up your error reporting if you can. During a process, don't bail out on the first error if you can sensibly keep going. Try and show up further errors before admitting defeat. For example, if you're exporting a scene from a 3D app, the user will be pretty annoyed if they have to rerun the export 50 times, fixing one trivial little mistake each time. Edit, export, DOH! Edit, export, DOH! Edit, export, beat up tools programmer...

Consider doing a preliminary sanity-checking pass over your data to catch common problems. Don't force the user to wait for 10 minutes of processing before telling them they've named something wrong. Of course, you should also allow users to cancel lengthy operations.

Using exception handling is generally frowned upon in game code, but it can be great in tools. It's a nice easy way to let lower-level code throw-and-forget. Higher-level code generally has a much better sense of context, and is much better placed to construct useful error messages for the user.

Don't bother to output warnings. Despite all best intentions, users will ignore them and they'll just accumulate over time to form a big nasty unreadable mess which obscures actual information. For example, the cryptic green-falling-letters effect in "The Matrix" is actually just the warning message output from their renderfarm tools. True story.

It's perfectly valid to have a '-debug' or '-verbose' option in your tool to help you track down problems, just don't burden your users with lots of rubbish output. They don't need to know the names of all 5000 files that your tool loaded successfully, they only need to know the name of the one that failed.

Nobody Reads Documentation

The more often users come and hassle you the less time you've got for important programmer stuff. You've probably got lots of important meetings scheduled. Long meetings. In the cafe across the road from the office. By yourself.

So it's in your interest to have a good body of documentation available to point users at. And it's great fun nurturing your contemptuous-glaring skills when they come to you with simple problems which are plainly covered by the docs. They soon learn.

The main thing is to avoid the build up of rule-of-thumb oral history and superstition. This kind of voodoo always comes back to bite you in the end, so you're much better off nipping it in the bud with documentation.

Consider giving users write access to documentation, or use a wiki or some other user-editable system. Offload as much as you can onto the users themselves. They'll do a better job than you anyway.

HOWTOs and tutorials covering common tasks are particularly useful, and are nicely informal and easy to write.

If you can, check the master documentation of the tool in alongside it's source code. Firstly, it'll help you keep the docs in sync with the tool as they both evolve. Secondly, it'll reduce the likelihood that the docs will get lost in the mists of time. This tends to happen a lot when transferring tools and tech to other teams - the recipient team just assumes there aren't any docs.

Many tools end up with documentation consisting entirely of redundant menu-item descriptions. For example:

File->Open - open a file

This should be interpreted as a warning sign. Or a cry for help.


Article Start Previous Page 4 of 5 Next

Related Jobs

Bodhi Talent
Bodhi Talent — Columbus, Ohio, United States
[06.26.17]

Lead Unity 3D Engineer
Infinity Ward / Activision
Infinity Ward / Activision — Woodland Hills, California, United States
[06.23.17]

Senior Rendering Engineer
Infinity Ward / Activision
Infinity Ward / Activision — Woodland Hills, California, United States
[06.23.17]

Engine Software Engineer
Infinity Ward / Activision
Infinity Ward / Activision — Woodland Hills, California, United States
[06.23.17]

Associate Tools Engineer





Loading Comments

loader image