Specifications
The Design Specification document establishes how we organize and present that information in the User Interface.
It is often the common point of reference for sign-off by stakeholders - and provides guidelines and continuity throughout the process.
When viewing the Design Spec, business stakeholders have one agenda, the technical team another. The biz guys are looking at business requirements and workflow, the tecchies are looking at data structures and code objects. A Design Spec (often called a "Functional Spec" by the tech team) should provide the common ground for both worldviews:
- It is a set of screen-based visual images + behaviors
- that reflects the goals, tasks and workflows that have been described by the business side
- as well as the constraints and requirements of the technical environment
The trick is to create a document that is comprehensive, informative and readable.
Push active design to the forefront.
Most decision makers see the "vision thing" of what we're creating as a dance of screens, not as an abstracted Visio diagram (just watch their eyes glaze over). The sooner the design is turned into clickable HTML Wireframe, the better. I generally try to "annotate" my HTML prototypes with funcspec info, so that the model is itself a living document, but a good ole paper document has its advantages.
Why bother?
You know the story: The development team has already produced 50,000 lines of code - and now they call in an design person to "make it usable". Often one of the first things I do is to capture "what it is" in a Functional Spec (which never got written in the first place). It's scary how many products move forward without capturing the basics...
The "Design Specification" (I've also heard it referred to as a Conceptual Design doc, UI Spec, Interface Design, etc.) is the high-level overview that provides context and common ground for everyone on the team. Stylistically, it's the "illustrated novel" or "manga" version of The Vision: It offers screenshots, lotsa visuals, the essential functional points, and a lean Cliff-notes summary of the story. Just the sort of thing that attention-deficient stakeholders might be willing to scan for a couple of minutes. Combine it with a shallow-working HTML model, and you might actually convince them.
If your working environment doesn't clearly define the document role, you might want to evangelize. The Design Spec document is strategically influential. If you own it, you swing some heft in the process. Even those who huff & puff about RAD ("We don't need no steenking documentation") will probably still embrace this "documentation lite."
Stylistically, it's the "illustrated novel" or "manga" version of The Vision: It offers screenshots, lotsa visuals, the essential functional points, and a lean Cliff-notes summary of the story. Just the sort of thing that attention-deficient stakeholders might be willing to scan for a couple of minutes. Combine it with a shallow-working HTML model, and you might actually convince them.
Disclaimer: I've been a Tech Writer and Documentation Manager. I believe that documentation is underappreciated within the process, often poorly executed (esp. in terms of "nobody wants to wade through it"), and absolutely critical to our success. As the "designated communicators" in the development environment, it's ultimately our responsibility to advocate it. I often try to be a "liaison" among the various team cultures - collecting, interpreting, translating, and serving info up as appropriately as I can.
Project Overview
This short "one page story" is the accessible, descriptive overview that should accompany any well-conceived discussion. In my own writing, I append such an overview at the head of every document produced for the project: It is the context for all that follows:
Business Case
Describe (at a high level) "why we need it" - the purpose and goals . from the perspective of the client and the enterprise. It is the highest level of description and lays the justification for the business requirements. This may include:
- Perquisites and dependencies on previous products
- History
- Legacy Issues
- Target audience
- Anticipated impact
- Market Forces
- Competition
- Perceived customer motivation
Actors & Roles
Identify (at a high level) who can do what . We have to know who we're talking about and how they work. This is particularly critical to our ability to design a "customer-centric" product.
- Roles
- Tasks
- Use Cases
- Permissions
Goals & Tasks
Assumptions & Risk
Product Perspective
Describe the relationship of the system being developed to other related system products or components, including a general description of the technical interfaces. This may include:
- Hardware interface requirements (i.e. Technical perspective)
- User interface requirements (i.e. Design perspective)
- Marketing or client-specific information which helps to put the product capabilities into perspective (i.e. Business Perspective)
The trick is to create a document that someone actually wants to read.
Workflow Map
You can create or edit Executions and add Purchase Contracts and Sales Contracts to their affiliated Loadings. Every Execution consists of one or more Loadings. Every Loading consists of one or more Purchase Contracts and one or more Sales Contracts.
The Overview captures the basic business goals and functional outline concisely. The Workflow is a high-level visual "snapshot" of the Tasks.
Stakeholders & Actors
The Execution Staff can view, create and edit Execution records and their affiliated Loadings. They can Settle Loadings. They cannot manage Overfills and Underfills.
Traders and Trade Admins can view Executions and Loadings. They cannot Settle Loadings. They can manage Overfills and Underfills.
Accountants can view Executions and Loadings. They cannot Settle Loadings. They cannot manage Overfills and Underfills.
| Task | Function | Use Case | Permission |
| Search & Select | Search & select Executions and Loadings | UC14 | Execution Staff, Trader, Trade Admin, Accountant |
| Create Execution | Create new record | UC11 | Execution Staff |
| Edit Execution | Edit existing record | UC12 | Execution Staff |
| Create Loading | Add Purchase Contracts, Add Sales Contracts | UC15 | Execution Staff |
| Edit Loading | Add Purchase Contracts, Add Sales Contracts | UC16 | Execution Staff |
| View Execution / Loading | Print Loading, Settle Loading | UC13, UC17 | Execution Staff, Trader, Trade Admin, Accountant |
| Manage Overfill | Contract overfilled | UC19 | Trader, Trade Admin |
| Manage Underfill | Contract underfilled | UC20 | Trader, Trade Admin |
We know which Actors have Permission to perform a Task. Tasks are generally identified in Business Case and Business Requirements documents. Every primary Function is captured as a Use Case ("UC") , which is described in a separate document.
Screenshot
Execution Staff can create and edit (Traders, Trade Admins and Accountants have View-Only permission).
Clickable items in the Search Results table go to either Edit or View pages, depending on your permissioning.
The screenshot provides a visual reality check for style, layout, understandability, appropriateness and conformance to presentation standards.
The sooner it's HTML, the better.
Page Elements & Controls
| Item | Type | Action | Bizrule |
|---|---|---|---|
| Search Results Table | table | Populated by system: Execution ID, Vessel Name, Loading ID, Loading Type, Status, Profit Center, Commodity Group, B/L Date, Loaded Quantity, UOM |
BR155 |
| Execution ID | link | Go to Edit Execution page. | BR127 |
| Loading ID | link | Go to Edit Loading page. | BR128 |
| Add+ | link | Go to Add Loading page. | BR148 |
| Settle | link | Begin Settlement process. | BR160 |
| Create New Execution | button | Go to Create Execution page | BR156 |
Every Functional (i.e. clickable) Item is identified by Type and described by Action. We identify the appropriate, underlying Business Rule ("BR") and describe it in a separate document.
View the case study in my portfolio: Bunge Global Markets
How does it work?
What are the boundaries of a Functional Specification? Seems to differ from team to team. Often it's a huge, unwieldy all-of-the-above doc that's hard to create, maneuver or manage. As such, it's inappropriate for a small-team Agile environment. Plus - nobody wants to read it. And, even tho it *should* exist before work begins, of course it never does.
At the high level:
- Break it out into manageable chunks
- Each with an appropriate author and voice
- Robustly cross-referenced (to avoid redundancy: one-source)
Product Snapshot: Overview (Product Owner)
Business Requirements: What, not How (Business Analyst)
Technical Specifications : Constraints, Data (Development)
Design Specifications : Presentation, Behavior (UX)
Craft additional detail as you move into the project (scalable)
Collaborate with other team players, s.a QA, on relevant issues
Net/Net: Documentation is the manifestation of Process. It's a skillset in its own right - the sort of thing that UX should advocate. After all, docs are useful only to the extent that they are usable.
Identify the "HOW"