DesignAday

Working with Developers: Documentation

Design documentation is not a one-size-fits-all product. There are a lot of differences between a small partnership building their own iApp and a software development firm doing millions in government contracts. Their documentation requirements are completely different. We need to design our documentation with the users in mind—specifically, the users of the documentation. Some documentation is intended for the customer. A lot of documentation is produced for the developers. It is important, then, to think about how the developers will be using the documentation.

I’ve been striving to design my documentation as a reference. That is, I try to make it easy for the developer to find information they need in the middle of development. Sure, I expect them to read the documentation ahead of time, so that they understand what they are to do, but it perfectly fulfills its purpose when, in the middle of coding a function, the developer has a question and is able to quickly find an answer. Long paragraphs of textual description and even bulleted lists are not the most accessible formats for such a use case.

In Comparison: Multiple Selection, part 3

Parts 1 and 2 of this series of posts were the result of my exploration to determine the behavior I would specify for a new, browser-based UI. Now that I’ve explained how it works in Windows XP and Mac OS X Lion, it’s only proper that I wrap up by relating my own design rational.

I sat down with the developer who is to implement the feature and went over my findings. She agreed that including an item that was just deselected in a new ranged selection seemed like a bug. While I like the flexibility of Apple’s implementation, I agreed with her that for our purposes, it was needlessly complex. Together, we settled on a single anchor. We decided to set the anchor on clicks and shift-clicks and to not move the anchor for control-clicks. We also decided that, to keep things simple, we would never deselect items on a shift-click. This goes against the standard desktop behavior, but my thinking is that the average user doesn’t likely realize the intricacies of such interactions. As long as we do something that is sensible and internally consistent, I doubt it will be noticed.

I documented the behavior in a series of Interesting Moments Grids, like the one below, that the developer will reference during implementation, as well as during testing.

Design Documentation: Change Sheets

I create very detailed user interface design documents for the software I work on, and for major applications, the documents can be relatively long. During implementation, many unforeseen factors may require changes to the design, be they technical limitations, time constraints, or additional requirements. It would take too much time to update the full design specification every time I had to make a change to the UI, so I instituted the use of change sheets.

A change sheet is created for the following purposes:

1. Document the change so that there is a record of what was changed and why. I go through so many versions of a design that it is often hard to remember where I ended up on certain issues and why I did what I did. Having a record of decisions is crucial, unless you want to solve the same problem multiple times.
2. Specify what has to be changed and how. This is the detailed specification for the developers to implement the change. The change sheet should include a visual mockup depicting the change and detailed explanation of behavior.
3. If necessary, get client buy-in before changes are implemented. Not all changes require customer approval, but when one does, a change sheet is a great mechanism for ensuring they fully understand what is being changed and why.
4. Compile as a reference for updates to the next version of the full design spec. Eventually that large document will have to be revised and submitted. Your stack of change sheets is the record of updates.

If #3 isn’t necessary, than the client may not be made aware of the change until #4. If I was calling our customer for every little tweak we had to make during implementation, I’d never get anything done, and the customer would be annoyed with me for constant interruptions. Establish a customer relationship of trust—they need to trust you to make all of the little detailed decisions that will result in the best product. The change sheets are your insurance policy in case they come asking questions.