Software Development Tip: Write and Maintain a “UI Map”

If the software you work on ever ends up with more than a few dialogs or a non-trivial navigation flow, then you should create a document that I call the “UI Map”. This document is quite simple to create, and the work you put in to it will pay off many, many times over. A UI Map is basically just a Word file (or pick your favorite editor, or wiki, etc.) that documents every single dialog and major state that your application can be in.

For the version 3.0 release of Paint.NET I finally created one of these at the behest of the translation team I’ve been working with, and I’m glad I did! The primary goal of this for them is to document every localizable piece of text in Paint.NET. For the new versions that I put out, it’s important to keep this document up-to-date and to spell out what is new or changed, as well as what text can be localized versus what text is supplied by the operating system (or framework, or user, etc.). Sometimes there are differences between how the UI appears in XP versus Vista (or versus 2000, 95, 98, Lunix, take your pick), and if those affect localization (or whatever your audience is interested in) then it should be noted in this document as well.

It’s very convenient for translators to be able to test that their translation does not cause layout or other visual errors, such as clipped text or worse. (And to point the finger in the right direction, it is not actually the translation that causes the error. It merely helps to expose the bug that was already there! :)) This will give them a visual tool to work with, and also makes it really easy for them to connect the text they’ve translated with where it shows up in the UI! That last part is very important, because usually a translator just sees this:


<value>This plugin is now built-in to Paint.NET, so the old plugin DLL has been blocked from loading. You may safely delete this plugin DLL.</value>


If I hadn’t written the code myself, then I’d have no idea where to find this text in the UI and clueless when it came to validate that it showed up properly (no clipped text, scrunched layout, etc.) It won’t kill you to spend a few minutes to tell them exactly how to reach that text in the UI.

Maintaining this document with every new version also forces me to touch and re-touch every part of the UI, which is important to increase confidence in a release. I’m not always the most diligent when it comes to testing things (shh, don’t tell anyone!) and so this is a very good exercise to require myself to do. In the new Paint.NET v3.20 release I have completely reorganized the Effects menu and revamped most of the effects’ user interfaces using the new IndirectUI system. I even found a bug while I was updating the UI map!*

Notice the scrollbar and the clipped text? Yeah, oops is right. No doubt there will be more bugs like this once I do a test pass with the other languages.

Having a UI map also makes sure that you don’t forget about any part of your UI. Remember that out-of-the-way error dialog you added three days before you shipped? Yeah, that one! On a fully professional project with a large team you might think this is taken care of by the design and documentation process, and you’d be completely wrong. The UI map can also help new developers on your project to get a quick visual tour of the application. Or new managers. Or higher-up managers or marketing folks. A document like this can serve as a valuable quick-summary for all of them, or even as a reference book. There is just so much value in having a UI map.

To get started, I use the outlining feature in Word. This way I can use the indentation level as an implicit navigation guide within the application. Here’s an abbreviated excerpt from the Paint.NET UI Map that shows how I’ve documented part of the File menu (up through “New” and “Open”), with screenshots resized in order to fit more appropriately on the blog. I start out by explaining the specific purpose of the document as well as certain constraints that are important. For example, it is implied from the 2nd paragraph that if text is cut off at 800×600, but looks fine at 1024×768, then that is not something of concern.

(Also, as another tip, I highly recommend using Kenny Kerr’s
WindowClippings program for making the screenshots look super professional. It captures the glass and drop shadow effects in Windows Vista perfectly. It’s what I use. And no, this is not a paid endorsement :))

Paint.NET v3.20 User Interface Map

This document exhaustively details the Paint.NET v3.0 user interface. It is meant primarily for translators to be able to find every location in the user interface for translation-related testing and tuning. Each part of the UI will be presented with a screenshot. The outline hierarchy implicitly shows how one can navigate to a particular part of the UI. This document is not meant to provide sufficient documentation on how to use Paint.NET and its various features. It is also not meant to be instructional on how to prepare a language pack for Paint.NET. Most error dialogs will not be detailed.

NOTE: Paint.NET’s system requirements list a screen resolution of 1024 x 768. It is important that UI elements work comfortably with a maximized window at this resolution with the Windows task bar set to one (1) unit of height. The main concern here is the help and context texts for the tools, which should not be clipped at this resolution with a maximized window. Paint.NET is not designed or optimized for smaller resolutions or window sizes (e.g. 800×600, or 1024×768 with a smaller window).

1. Application
This is the interface the user sees when they start Paint.NET. By default there are four docked floating toolform windows (aka floating windows, floating tool windows).
(screenshot removed for brevity)

1.1. through 1.4 – (removed for brevity)

1.5. Menu bar

1.5.1. File
(new for v3.20: View Plugin Load Errors…) New
When the user creates a new image, it will be called “Untitled”. This name is localizable. Open
This is a common Windows dialog. Most of the text on it is provided by Windows. The file type drop down has some strings that are localizable:
(New for v3.10: “DirectDraw Surface (DDS)” is now a supported file type) In Windows Vista, the dialog will look like this instead:
If the user is transferring files from a location that is not mapped to a file system path (such as from an http:// source, or from a digital camera that is not mapped to a drive letter), then they will see the following UI:

If the user cancels the transfer, they will see this while the transfer is being canceled:

If there is an error while transferring (server error, camera failure / disconnect), then this dialog will be shown. Note that the error message (“A device attached…”) is provided by the OS and/or the .NET Framework, and is not localizable. It will generally be supplied in the language that the OS and/or Framework is configured or installed for.

* To be fair, a member of the forum, “I Like Pi,” actually pointed this out first. I would have discovered this much sooner however, if I had updated my UI map two weeks ago instead of waiting until tonight!


8 thoughts on “Software Development Tip: Write and Maintain a “UI Map”

  1. Li Yang says:

    An important feature request is that Paint.NET is not only a tool but also should be a great library for developers.

    The pity is that when I looked into the source code, I got lost and could not easily find components reusable. For example, Paint.NET’s elements (open/save file dialogs and command links) work fine on both Windows XP and Vista, but I cannot easily add this elements to my application easily.

    If possible, please place these fancy components in one or more class libraries so I can incorporate them into my application.

  2. Rick Brewster says:

    Li Yang — The Paint.NET source code is provided as-is and for educational purposes. It is not intended to be a library or SDK for other applications. If you want to re-use its controls like that, you’ll just have to put in the work to make sure they’ll work in your program.

    Michael — Depends on what you define as “deal with.” There is a bunch of text in there that is still provided by the application and is thus localizable, such as the file type/codec descriptions. The goal of the UI map is to document the whole UI, which includes the Open/Save dialogs, yes? Not everyone is entrenched in the Windows SDK and knows which dialogs the OS or Framework “deals with”. There is also some UI that I have added myself, such as the “Transferring…” dialog. It’s important to include *every* dialog even if you just notarize it with, “The text on this is provided by the OS and is not localizable”.

  3. Michael says:

    Rick, I was referring to Li Yang’s comment, where they were wondering how PDN manages to use the open/save dialogs etc.

  4. Rick Brewster says:

    Michael — Ahh, makes more sense now. Although Paint.NET does have a large amount of code to make sure it can make use of the enhanced Open/Save dialogs in Vista. This is not something that .NET provides for you until .NET 3.5 (or so the feature list states, I haven’t tried it out myself).

  5. The_Lionhearted says:

    Very interesting Rick! Thanks for sharing another “trick of the trade”. 😉

Comments are closed.