What We're Going to Build
In this post we'll walk through the application that we're going to build out and compile the list of documentation that we want in place prior to starting the development process
Guide Tasks
  • Read Tutorial

“Give me six hours to chop down a tree and I will spend the first four sharpening the axe.” - Abraham Lincoln


When I was new to development, I always wanted to dive straight into the code, the sooner I started typing the sooner the application would go live, right? As my experience grew I slowly started to realize that when I spent the proper amount of time planning out the application I was able to save an exponential amount of time during the development stage and the applications ended up performing much better compared with when I 'dove' into the code right away.

Since this is a course that has the goal of training you on how to become a professional Rails developer it's important that we follow the same steps that you're going to follow for a real world application. I've taken years of graduate school courses on software engineering, built countless products for clients (including organizations such as Eventbrite and Quip), and the engineering concepts that we'll go through are the refined processes that I've learned over the years. I like to think it combines formal and practical techniques in a way that helps projects go from start to finish as successfully as possible. So without further ado, let's get started.

Software Engineering Template

Below is a checklist that I follow when approaching a new project. I have the rule that no code gets written until each of these items are completed:

  • List of key stakeholders - this lists out each of the individuals involved in the project, this can include, but isn't limited, to the following: developers, QA testers, project managers, DBAs, software engineers, and anyone else who will work on the application, along with their role and contact information. This may sound trivial, however I can't tell you how often I've used this to contact someone, especially at the beginning of a project

  • A revision history - no project ever matches the original requirements, there are always going to be changes, some of them small, some large. It's important to track scope or feature changes throughout the development process. This limits conflicts later on since it forces stakeholders to take responsibility for when they've requested a change to the project

  • Table of contents - self explanatory

  • High level summary and project introduction - this portion of the document describes what the application will do. This should be very straightforward and be readable even by non-technical individuals. It should include the Purpose of the project, the System Overview, and any Important Terminology

  • Overall Description - this portion of the document is where we get into the nitty gritty of the application, including a comprehensive list of the product requirements, which will have requirements for the database, user interface, functional requirements, and the architectural requirements

  • Project Challenges and Proposed Solutions - too many times I've seen developers leave the hardest parts of the application to the very end. I prefer to list them out in the very beginning so that the team can propose solutions. In this stage there also are times where it's decided that a project shouldn't be built. Does that sound bad? It's not, in fact, it's a very good thing. Would you rather start a project, waste time and money building out basic features to have it canceled later on? I can tell you from experience that this makes for some very frustrated clients. Just recently I had a project that got to this project challenge stage and it was discovered that one the core features wouldn't be possible because of some hardware issues. The client was very pleased that no money was wasted and my team was rewarded with an even larger project!

Over the next few guides we'll walk through each of these elements and create a professional requirements document that we will use to build out application.

App Introduction


The application we'll be building is called DailySmarty. It's a knowledge engine that will let users post about things that they learn each day. Following the principles from Malcolm Gladwell's book, The Tipping Point, we will let users track how long they spend learning a topic so they can watch themselves go from a beginner to mastery. This will include features similar to Facebook's Newsfeed, the ability to have friends, the ability to edit authorized friend's posts, and all of the features you can imagine being associated with a knowledge based social network.