One of the hardest things to do when building a software product is effectively communicating your ideas to your development team. In addition, these issues are usually magnified when you’re early on in your product process. Generally, communication issues between stakeholders and developers fall into “macro details”. “expected behavior”, or “user interface concerns”.
Despite being an oxymoron, “macro details” captures the types of errors that occur at the architecture level. For example, imagine you were building a calendaring system for intramural sports teams where each team manages their games for the season using the calendar. A “macro detail” would be that each “team” owns a single “calendar”, a potential error then would be the development team coming back with a solution where every “player” on a “team” owns a “calendar”. Following from that, the “expected behaviors” of the system would capture issues like “what happens if two teams try to schedule a game for the same day?” or “can a player be on more than one team?”. A defect then would be that the stakeholders expected the system to not allow multiple games on the same day but the system allowed it. Finally, “user interface” concerns would typically encompass how the various components of the application are organized and what the different screens are.
Great, so how do you avoid these problems? What follows below is a loose framework for mitigating these issues, it certainly isn’t original but rather a synthesis of techniques that I’ve seen help power effective communication.
Oh hey, from 10,000 ft.
For a totally new product, getting started is often the hardest part. Usually, the entrepreneur or executive who is building the product has been frantically planning, talking about, and “living” the product for sometime before the project actually kicks off. The result of this, is that the stakeholder intimately knows the ins and outs of the project but the rest of the team won’t necessarily be aligned with the primary stakeholder. Because of this, starting by writing a 1 – 2 sentence “10,000 ft. view” is usually a great first step. Using the sports calendering example from above, you might end up with:
I want to build a calendaring application to allow intramural (think old man kickball) sports teams to collaboratively plan their games for the season.
Who, What, Where?
With the “big idea” down on paper, the next step is to start defining the primary objects in the system and how they are all related. At this stage, other people normally develop “user personas”, which describe typical users of the system, and then elaborate on how each persona will use the system. In my experience, this approach is effective but inexperienced stakeholders tend to get caught up in the details and ultimately have a difficult time reaching the right level of abstraction. Looking at the calendaring app, some of the objects you’d end up listing would include:
- Teams
- Composed of players
- Own a single calendar
- Linked to a single league
- Players
- Primary actor in the system
- Each user will be represented by a player and own a single profile
- Linked to a single team
- Calendars
- Owned by a single team
- Contain games on specific days
-
Leagues
- Comprised of multiple teams
Anyone that is familiar with Unified Modeling Language will notice the format is similar to how UML uses nouns and verbs but its a bit different. I’ve always had better luck using natural language to write out the relationships between entities and then converting that into an entity relationship model and then RDMS tables.
Rules, Rules, Rules
Once the primary entities are defined, the next step is to write out the business logic to minimize the confusion around how the system should work. There are formal structures for this as well, including behavior driven development, but in my experience its easier to kickstart the conversation with natural language specifications and then introduce BDD later in the development cycle. Anyway, running with the example you’d end up writing out something like:
- Users (Players)
- Can create accounts
- Can create games on a calendar
- Can join “Teams”
- Can’t join two Teams
-
Teams
- Created by “Players”
- Can’t be deleted after there’s at one member
-
Calendars
- Automatically created when a team is created
- Won’t allow two games on the same day
- Can’t be deleted
- Will only allow users to edit their own events/games
Like with the entity relationships, I usually start with natural language and keep the definition of “business logic” pretty loose so that I can capture as much information with the stakeholder as possible and then formalize from there.
Draw me a map
Finally, the last piece is usually communicating what the UI of the application should be. Depending on the makeup of the team, the amount of input that business stakeholders have in this respect might be minimal. However, if there isn’t a dedicated UI/UX resource available UI mockups will definitely be a valuable asset in helping communicate the vision of the application.
There’s several tools for developing UI mockups including Balsamiq, OmniGraffle and Mockflow. Generally, any tool you’re comfortable with will work fine but the key concern should be not “lowering” the designs too far to allow people to concentrate on the ideas, not the specific implementation. I’ve always been partial to Balsamiq since its attractively priced, easy to use, and the final mockups are more like sketches than a finished design.
Anyway, sticking with the calendaring project you might end up making a screen that looks like this:
Like everything else, the definition of UI mockups are generally flexible. Some people like to “lower” pretty fair to high fidelity designs and other people like to leave them at “pen and paper” type sketches. At the end of the day, it’ll be a project by project decision.
Wrapping up
Well thats a crash course, with examples, of how I generally work with key stakeholders to sketch out projects. Ultimately, figuring out the best way to communicate your vision to your engineering team is going to be a personal decision. You’ll probably end up having to mix together several techniques that take advantage of the skills on your team and match the requirements of your project.