Customer Guide

Hi! Welcome to Fit. You're reading this because you're a customer on a team that's either using Fit or considering using it. This document is here to help you get started quickly.

When we say you're a "customer," we mean that you're someone who has influence over the product your team is creating. You might be a user, domain expert, business analyst, product manager... anyone who contributes to the product from a requirements point of view. Programmers and testers sometimes double as customers, but it's not as effective as having dedicated customers.

Before we get started, you may want to read IntroductionToFit and FitWorkflow. They introduce Fit and provide a process for using it on your team.

The Customer's Role

As a customer, you have a valuable perspective on your software: you know what it needs to do. Your challenge is communicating that vision to the rest of the team. Even features that seem obvious can be misunderstood by your teammates, and even other customers. Fit exists to help you communicate your vision clearly and expose misunderstandings early.

Fit works with ordinary documents. You can create them in Word or any other tool that will save as HTML. (Ask your programmers or testers to help you pick a tool if need be.) These documents are your responsibility.

Customers are usually pretty busy people, and you're probably no exception. Fit documents can be hard to write, so you might be tempted to delegate them to testers or programmers. Don't do that! Fit documents are hard to write because they require absolute clarity. If you're having trouble providing examples for a feature, it's probably because the feature is complicated or hard to understand. Delegating that work will just ensure that you don't get what you want.

That doesn't mean you can't have help. Feel free to delegate to other customers--but make sure they understand the product as well as you do. Testers and programmers will suggest questions and areas that aren't covered by existing examples and technical writers can help improve the clarity of your Fit documents, too. But come up with the actual examples yourself.

Creating Examples

The heart of a Fit document is examples. The technique we use is even called "specification by example."

When you're starting a new feature, gather the whole team around a whiteboard as described in FitWorkflow. Explain the feature and provide some basic examples. Don't worry about formatting the examples in a table or anything like that--just provide a few examples of how the feature works and get the team to give feedback.

When you first get started, you'll be tempted to give all your examples in terms of what people will do with the software. You'll say things like, "Accounting will enter someone's timecard into the system here and press this button. Then the software will show a screen with everyone's compensation and they'll press a button to print the checks."

This sort of example will work with Fit, but it's not a great example. It talks about the steps people take and glosses over the important rules used to come up with actual compensation.

These underlying rules, often called "business rules," are hard to explain and verify. Fit is designed to help communicate these rules. Instead of giving a list of steps, trying giving examples that stand on their own and don't have to happen in a particular order. For example, you could say, "If someone works 50 hours in a week and is paid $20/hr, their pay is $1100 for the week." This will lead to the team to ask questions, such as "50 x $20 is $1000. Where did the extra $100 come from?" These questions will lead to valuable discussion about your business rules.

Thinking in terms of rules rather than steps is the hardest part of using Fit, but it's not Fit that makes it hard. Business rules are rarely articulated and often poorly understood. Thinking in terms of underlying rules is likely to expose questions that you'd never thought of before. Your software will be better as a result.

Creating a Fit Document

Once you have some basic examples, work with testers and programmers to put them, as tables, in a Fit document. Don't worry too much about adding descriptions above your tables yet--you'll do that later (see "Great Fit Documents," below). A few brief notes to help you remember what's going on is all you need for now.

Programmers and testers will help you structure your examples in a way Fit can understand. Make sure that the structure you choose doesn't make the example too confusing. Your teammates may suggest structures that don't make sense to you. Speak up when that happens. The examples should describe your thought process, not a programmer-oriented throught process.

After the initial Fit document is created, programmers will get started on implementing the new feature. They'll also hook up Fit so you can run it on your document. Ask them to show you how you can get the latest software and run Fit against it. This will allow you to see progress, add examples, and experiment on your own schedule.

As work progresses, testers will try to come up with scenarios that expose more rules. Programmers will also come up with questions. Work with them to flesh out these scenarios into more examples.

Throughout the process, your team should be constantly collaborating. Don't just hand your programmers a document and expect perfect software back. Be available to answer questions, review results, and create (and throw away) experimental examples to learn more about what the software is doing. Expect the same from your team. Expect them to be available to help you understand how to use Fit, come up with good rule-based examples, and answer your questions. You should always feel that Fit is an aid to communication, not a replacement for it.

Great Fit Documents

A great Fit document can be understood by a stranger who's familiar with your business. Examples are at the heart of a Fit document, but examples alone don't make any sense. Proceed your examples with a little text--not too much!--that explains what the examples describe. You can also use formatting like bold and italics to make the tables more clear.

A great Fit document

As you add features to your software, you'll accumulate Fit documents. Don't let them just pile up. Review them occasionally for duplication, combine related concepts into single pages, and use hyperlinks to organize them so they work together as a cohesive whole. Create an overview page for people to start with and hide detailed, nitpicky examples in links from more general examples.

Your goal should be to create a description of your software that can be used as a reference in the future. Examples alone are enough to create the software today, but with just a little more effort, you can create a long-lasting, useful document that will guide future development.


Fit is an important tool for communicating your vision to the rest of the team. To be successful with Fit, you need to take ownership of the Fit documents. It's not easy, but you'll love how much knowledge and control it gives you over the direction of your software, and you'll be more successful as a result.

by JimShore with contributions from (your name here). Last updated for v1.0.

This concludes the Fit documentation trail. The previous article in the series was FitWorkflow. You may DownloadNow or return to FitDocumentation.


Last edited September 24, 2020
Return to WelcomeVisitors