Rails and Product Planning

by Daniel Kehoe

Last updated 15 July 2013

This article from the RailsApps project suggests how entrepreneurs can plan software development for startups and personal projects. It describes product planning with “user stories” and introduces the concept of behavior-driven development as part of the software development process.

If You Are New to Rails

If you’re new to Rails, see What is Ruby on Rails?, the book Learn Ruby on Rails, and recommendations for a Rails tutorial.

What is the RailsApps Project?

This is an article from the RailsApps project. The RailsApps project provides example applications that developers use as starter apps. Hundreds of developers use the apps, report problems as they arise, and propose solutions. Rails changes frequently; each application is known to work and serves as your personal “reference implementation.” Each application is accompanied by a tutorial so there is no mystery code. Support for the project comes from subscribers. Please accept our invitation to join the RailsApps project.

Software Development Process

Some people think software development begins with writing code. But in fact, product planning is the first stage of the software development process. Product planning, which is at the heart of going from “concept to code,” is critical in getting a project off to a good start.

Arguably, for a simple application you build yourself, you don’t need a lot of “ceremony.” There’s no need for a written specification. Just write some code. But though your application may seem simple, if you’re a solo operator, product planning can be helpful. Software projects have a tendency to grow complex and take longer than planned. At a minimum, product planning will help you focus your ideas before you begin coding. If the application grows complex, it will help you track progress and stay on course.

For ambitious projects, when you are part of a team, or when other people’s time and money are at risk, product planning is a key element of a robust software development process. If you plan on growing a company, product planning is fundamental.

It’s up to you to decide how much time you will spend in product planning. But consider some of the benefits:

• It helps you discover the functionality you need to implement.
• It helps you describe and discuss features with your business partners.
• It serves as a “to-do list” to help you track progress.
• It is the basis for acceptance testing or integration testing.

A robust software development process will also include project management and testing. See an article on Rails and Project Management for more on project management.

Product Owner

Who is in charge of deciding what features and functionality will be included in an application? If you are a startup founder or building your own project, it’s obvious, you are in charge of defining what your application will do. You are the product owner.

But think for a moment about the more difficult role of a student who is given an assignment, a consultant who builds a client’s project, or a team in a corporate development environment. Someone has given you the task of building an application. Somewhere between the lofty goal of the project and the implementaton details lies a grey area of product features and requirements. Typically a client or executive management will not provide a fullly developed specification of product requirements. And many developers just want to know what to build. Into that void steps the the product owner.

The product owner can be a technologist or a business person. The responsibility is to look at the application from the point of view of the application user and decide what features and functionality are essential for the user and what must be left out. Without a product owner, a project can collapse in vagueness or drift by whim, ultimately satisfying no one.

User Stories

A product owner’s principal tool for product planning is the user story.

User stories (definition: user stories) are a way to discuss and describe the requirements for a software application. The process of writing user stories will help you identify all the features that are needed for your application. Breaking down the application’s functionality into discrete user stories will help you organize your work and track progress toward completion.

User stories are often expressed in the following format:

As a <role>
I want <goal>
so that <benefit>

As an example, here are user stories for the rails-prelaunch-signup application from the RailsApps project.

*Request Invitation*
As a visitor to the website
I want to request an invitation
so I can be notified when the site is launched

*See Invitation Requests*
As the owner of the site
I want to view a list of visitors who have requested invitations
so I can know if my offer is popular

*Send Invitations*
As the owner of the site
I want to send invitations to visitors who have requested invitations
so users can try the site

*Collect Email Addresses*
As the owner of the site
I want to collect email addresses for a mailing list
so I can send announcements before I launch the site

*Social Network Sharing After Sign Up*
As a user
I want an option to post to a social network after I sign up
so my followers will learn about the site

We can use this list of user stories as our task list in implementing the application. The article Rails and Project Management shows how you can track progress implementing user stories with a simple to-do list or more complex project management tools.

Behavior-Driven Development

Behavior-driven development (BDD) is a software development methodology that uses user stories as a basis for automated testing. User stories are turned into scenarios that are accompanied by tests. With automated tests, a product owner can determine if developers have succeeded in implementing the required features. This process is called acceptance testing. Automated tests also make it easy for developers to determine if the application still works as they add features, fix bugs, or reorganize code. This process is called integration testing.

Here’s how user stories can be the basis for behavior-driven development using Cucumber:

• write user stories
• user stories become Cucumber scenarios
• create acceptance tests based on Cucumber scenarios
• code each feature
• run acceptance tests as each feature is completed

Cucumber scenarios turn user stories into plain-English descriptions of a series of steps to execute a product feature. Cucumber is appropriate when a team includes nonprogrammers who are involved in defining product requirements or there is a need for a specification and acceptance tests to be maintained independently of implementation (for example, when implementation is outsourced).

Behavior-Driven Development Without Cucumber

There are alternatives to Cucumber that may be more appropriate for smaller projects or teams of people who are comfortable reading software code.

Many Rails developers create integration tests using Capybara in combination with RSpec as described in Ryan Bates’s How I Test Railscast.

User stories can still be the basis of product planning using the RSpec and Capybara approach; instead of using Cucumber, features are tested with RSpec and Capybara but the features are still based on user stories.

Wireframes and Mockups

User stories are not the only technique you can use to plan a web application. Often, before writing user stories, a product owner will make rough sketches of various web pages. Sketching is a phase where you try out ideas to clarify your vision for the application.

Sketching can lead to a wireframe or a mockup. These terms are often used interchangeably but there are differences in meaning.

A wireframe is a drawing showing all functional elements of a web page. It should not depict a proposed graphic design for a website, rather it should be a diagram of a web page, without color or graphics.

A mockup adds graphic design to a wireframe; including branding devices, color, and placeholder content. A mockup gives an impression of the web site’s “personality” as well as proposed functionality.

One of the most popular tools for creating wireframes is Balsamiq Mockups (despite the name, it is for wireframes, not mockups).

There are dozens of others:

Axure
Balsamiq Mockups
Cacoo
Concept Draw
Denim
Designer Vista
FairBuilder
ForeUI
HotGloo
Inpreso
iPlotz
jMockups (HTML5)
Jumpchart
Justinmind
Justproto
Lovely Charts
LucidChart
Lumzy
MockFlow
Mockingbird
MockLinkr
Napkee
Pencil Firefox Add-on
Pidoco
ProtoShare
Prototype Composer
Quplo
Simulify
Tiggr
Website Wireframe
WireframeSketcher

Graphic Design

By necessity, graphic design is a separate process from application development. Very few people have skills as both a visual designer and a programmer. The tools are different; graphic designers typically use Adobe Photoshop, though web-savvy designers now often create designs directly in HTML and CSS.

If you’re lucky, you will have help from a skilled graphic designer as you build your web application. If you are very lucky, you may work with someone who is a user experience (UX) designer or interaction designer (IxD).

If you’re working with a graphic designer you might collaborate on a moodboard or a design brief to define the look and feel of your application. If the designer works in Photoshop, you’ll face the challenge of converting design layouts from Photoshop to HTML and CSS. There are service firms that do this for a fee but obviously it’s easier to work with a designer who can implement a layout directly in HTML and CSS.

Rails can be particularly challenging when it comes to integrating graphic design with code. Rails uses a hybrid of HTML markup mixed with Ruby programming code in its view files (depending on the stack you’ve selected, the view files can use ERB, Haml, or other syntaxes for mixing HTML and Ruby). Few designers are comfortable with Ruby code mixed with HTML so you may end up doing integration yourself.

If you don’t have a skilled graphic designer available to help, you can always use Twitter Bootstrap or other front-end frameworks such as Zurb Foundation to quickly add an attractive design to your application.