Ed Tech UI Guy

Monday, January 31, 2005

Links and Validation

We're at the stage in the gradebook project that every UI designer dreads. I need to provide detailed specs on application behavior, so the programmers have a plan to code to. I usually avoid this job - either I work so closely with a programmer that we just do them verbally as he codes, or the HTML mockups are so complete no specs are needed, or someone else does them.

The teams I've worked on call these specifications the "functional specs." The document at the beginning of the project that details what the application will and will not do is the 'scope statement' or 'requirements.' I'm only mentioning this because some teams call that early requirements document the functionals specs. I don't think that document is specific enough to be called 'specs' - I don't think it should be, either.

I've started functional specs for the Gradebook twice. Both times coincided with disruptions of the project, as the programmers realized that Sakai didn't have the framework to support the application yet. This time we moved on by scaling back the project drastically to do what we could with what Sakai currently offers new apps. This scale back meant many fewer screens, and much less to write!

We tried several approaches to writing these specs. By Friday in conversations with the two programmers on the team, Berkeley about what they needed beyond the wireframes, it became clear that 90% of their questions about the wireframes boiled down to initial view, links and validation.

  • Initial view: Who can see this page? Are any elements hidden from some people? What's the default value of the elements, the default sort order of the list? What if nothing has been added yet (e.g the assignment list before any assignments have been added)?
  • Links: What happens when each link or button on the page is clicked? What page comes up on cancel? Any special messages on submit?
  • Validation: Any time there are form inputs, what are the acceptable values? What needs to be checked before the form validates?

When I write up these answers for each page, they can be used with the wireframes as a complete spec. Any other questions that come up I can clarify adding notes to the wireframe itself. This isn't absolutely bullet proof, but as Ray (one of the team members at UCB) said "this isn't IBM." I can get the specs done is a few painless hours, and the programmers can get to work. I feel liberated from the fear of specs.