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).
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
(new for v3.20: View Plugin Load Errors…)
When the user creates a new image, it will be called “Untitled”. This name is localizable.
This is a common Windows dialog. Most of the text on it is provided by Windows.
188.8.131.52.1. The file type drop down has some strings that are localizable:
(New for v3.10: “DirectDraw Surface (DDS)” is now a supported file type)
184.108.40.206.2 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!