We're Hiring!

Planning & prototyping

Understanding requirements and writing specs

This is Joel Spolsky’s excellent definition of functional and technical specifications:

A functional specification describes how a product will work entirely from the user’s perspective. It doesn’t care how the thing is implemented. It talks about features. It specifies screens, menus, dialogs, and so on.

A technical specification describes the internal implementation of the program. It talks about data structures, relational database models, choice of programming languages and tools, algorithms, etc.”

- Joel Spolsky, Painless Functional Specifications - Part 2: What’s a Spec?

We develop technical specifications in an Agile fashion. First, overall technical architecture is specified and second, a more granular per story level of detail is specified.

Our approach to functional specifications is ‘just enough’.

We want to understand the customer’s needs and their domain, but we do not want to over-specify things for the sake of it as it generally goes against the ideas of Agile and continuous delivery.

A functional specification can be thought of as a document that records the choices the team make - it is an ongoing process. It supports the key things upfront that we have decided to develop as a minimum viable product (MVP) and then builds upon that as we go.

Understanding the company’s business is the largest and most important part of getting specifications ‘right’. If we design an elegant solution to the wrong problem, then the solution will fail regardless. Often the problem is not obvious - companies may be looking at symptoms and trying to fix those. It is our job to identify the problem rather than merely introducing patches for symptoms.

Given this approach, people are normally the most important component. Gathering knowledge of the customer’s employees, processes, and working patterns is key. To achieve this, we typically send a small exploratory team to be introduced to the customer’s team. We look to understand the entire working day of the people who will be impacted by the software solution. Sometimes in larger projects this is broken down into several sessions. We try and understand where the customer is and where they want to be - fundamentally a Gap Analysis, with proposed solutions flowing from that.

Before we start writing functional specifications we should be able to clearly define the goals of the project, what we think the return on investment of those goals will be, and have the customer agree with this.

The functional specification should cover the following points:

  • Define the goals of the project
  • Define the user control flow
  • Define the system architecture
  • Define the system infrastructure
  • Define the database model
  • Define the interfaces to APIs and other systems
  • Define the target platforms
  • Define the non-functional requirements

A specification should have one lead author. Several people may be involved in gathering knowledge and putting together the solution, but one person should oversee coherently putting the document together. There may be other editors but one person has final responsibility. This ensures that a specification reads with clarity.

“But no one reads the spec”

Keep things simple. Do not bamboozle the customer with unexplained acronyms or verbose prose. Trick people into reading it by presenting it in small pieces. Gather feedback. Do not use templates, they force linear approaches to nonlinear problems. Review often. Keep ROI in mind. We always balance the breadth and depth of a specification with the size of a project. Specifications are time intensive processes, but a necessary process to define the scope and capabilities of a piece of software.

Prototyping in code

Although we are a very design-centric company, we do not have any dedicated designers. Why? Because we believe it creates a disconnect between the realities of the implementation and the design process itself.

Carefully crafted static designs might look nice on paper as something to present to the key decision makers, but for us, they fail in three distinct areas. First, they are fundamentally incompatible with an Agile process. Second, they usually fail from a user experience perspective and third, they add a lot of complexity to implementations.

Instead, our design skills are scattered amongst our team. Some team members, we admit, should never be let near a colour palette! But that is fine, they agree too! Others in our team have strong design and interaction roots.

From the customer’s perspective, frameworks are so powerful nowadays that they shouldn’t be paying for lengthy Sketch mockups. We build design into our entire process and implement it with the same tools we program with. Frameworks allow us to create working prototypes and designs directly in code. This is by far the most efficient way of approaching this task.

The clear majority of our deliverables are cross platform, which only compounds the efficiency of prototyping straight into code as soon as possible. Our approach is to prototype for the platform we have identified as the key platform first, then iterate those prototypes down or up in size to other platforms only once all the key problems have been addressed on the main platform. This ensures that designs are adapted to play into the various strengths and weaknesses of different viewport sizes.

So why do we prototype?:

  • To challenge our preconceived ideas about how well solutions will work
  • To reveal potential problems in our solutions
  • To test the visual look and feel
  • To identify problem-areas far in advance

Whom do we prototype for?:

  • The key stakeholders
  • Internal Users
  • External Users
  • Customer
  • Developers

We embrace a process of rapid prototyping, combined with continuous delivery. Rapid prototyping is a methodology of creating ‘working prototypes’ as early and as fast as possible.

Our process through to final product generally looks a lot like this:

Each stage of the process is driven by the rapid prototyping methodology involving the customer and key stakeholders.

Low Fidelity Medium Fidelity High Fidelity
Pen and paper Rough code rapid prototype Interactive functional prototype
    Final polish

During the prototyping phase, we find it important that we work with data that is as realistic as possible. Sometimes we must work with ‘lorem ipsum’, but where possible we work with the customer early on to get a feel for the kind of data we will really be working with further down the line. This helps reduce misunderstandings or bad choices early on.

Getting Prototype feedback

The value of prototypes is greatly reduced if they are done in isolation. For a successful rapid prototyping cycle, the ‘review’ phase is critical. This means gathering feedback from various stakeholders, often primarily the customer.

Present mock-ups in the right context. If you are at the low or medium fidelity stage, getting feedback on the colour of buttons isn’t of much value. Getting feedback on what those buttons do is critical.

Here is our process:

  1. Define up front if you are testing form, function, interactions, or a mixture of these. Lay this out to the user.
  2. Have a clear goal for your mock-ups. Challenge your assumptions.
  3. Collect enough feedback to be able to act.

Using judgement is critical. Design by committee typically results in weak design. In the interests of simply adding feedback for the sake of it, people often ask for changes that detract from the design. Do not be afraid to say ‘no’ if you feel strongly about it.

The more people we collect feedback from the better.

It is important not to get hung up on getting things ‘perfect’ - the nature of Agile is that we can adapt and improve later in the cycle once we put things through their paces. Prototype testing can only go so far.

It is important to note the clear distinction between ‘feedback’ and ‘user testing’. ‘User testing’ comes later in the process and we have dedicated an entire section to this later in the Blueprint.

QCon London

QCon London is a conference for senior software engineers and architects on the patterns, practices, and use cases leveraged by the world’s most innovative.

March 4-6, 2019 Find out more