Building Subtract.Online
Note: I drafted this post around May 7–9, 2018, as I was beginning to design this project. The publication date says June 8 because that’s when I decided to share it. I don’t expect readers to be interested in every detail presented here; many of my initial plans have changed and evolved anyway. This is just an outline of the general process that I followed in the early stages of planning. I’d be thrilled to talk with anyone about the process and/or the app!
Introduction
I am embarking on a project which will provide me a chance to practice building a web app with Rails 5.1 and Vue.js. The finished product will be a math review tool for my daughter who is currently finishing up first grade.
I’m designing this project from scratch, and I’d like to take this opportunity to briefly write out each step of the Agile process I’m following. These steps are from Launch School’s free online book, Agile Planning.
Personas
I’ll call my user Jennifer. She’s 7 years old, finishing up first grade, and this year she’s learned a lot about addition and subtraction of whole numbers up to 20. Her teacher has encouraged the students to use a specific website where they are given 6 seconds to answer each math question. Jennifer finds this very stressful and she avoids it as much as possible. It’s easy when she already knows the answer, but if not, 6 seconds is not enough time for her to figure it out.
Scenarios
- Practicing. The app presents Jennifer with a math problem and then allows her as much time as she needs to figure it out. There could be a UI where she can manipulate elements to find her answers. She practices for a reasonable amount of time, then the session ends.
- Keeping data. The app remembers math facts Jennifer has practiced before. It keeps track of the time it takes her to answer a problem during a session.
- Viewing progress. The app can display a list/chart of the problems Jennifer can answer in 5 seconds.
- Signing up. Jennifer’s mother navigates to our web app, signs Jennifer up, and adds a shortcut to her tablet. (For simplicity, our app doesn’t require email validation, just a unique username. It will attempt to safeguard children’s privacy by not collecting or sharing sensitive information.)
- Logging in and out. Staying logged in with cookies is not necessary. There is a log in/log out button.
- Incentivizing/motivating. Jennifer wants to practice because there is a reward involved.
The Core
The core of this app is practicing math facts.
Wireframing
Prioritized/ordered backlog of stories broken down from epics:
Starting with epics and breaking them down to stories was an incredibly useful process!! There were all sorts of features I thought of for this project, and I knew I needed to narrow them down but I had a hard time giving up some of the features that seemed “cool”. Thinking empathetically about what my user would actually want and why as she attempted to meet her own goals proved to be the key!
I was happy to realize that I don’t have to start with the landing page/sign up/log in. Of course those things will be essential but there are good reasons to start with the core functionality. Most importantly, I can have actual users test it and give feedback.
I am also enjoying the experience of seeing details get ‘fleshed out’ or ‘broken down’ bit by bit. As I began to conceptualize this app, I had a few ideas that I wanted to incorporate but hadn’t quite articulated, even to myself. As I worked on breaking down the stories into finer, testable bits of functionality, this happened very naturally. For example, ‘As a child, I want math problems to be presented in a progressive order of difficulty so that it doesn’t feel overwhelming’ got broken down into stories related to the concept of ‘mastery’. As I wrote tests, ideas about implementation started creeping in. I decided to jot them down, with the understanding that the implementation could change.
Here are the stories I plan to start with, in an order that makes sense. Acceptance tests in italics follow each story.
As a child user, I want to see the math facts I’ll be working on next and those I’ve mastered so that I have a sense of progress. | A starting view will display the problems, a brief explanation, and a way to start (ie start button). Problems can be generated by the program but each problem should have a unique identifier.
As a child I want a clean, attractive UI for solving problems so that I can stay focused. | A practice view will present the problem and a text input (number) for the answer. When a correct answer is typed in, the view responds immediately.
As a child I want an incorrect answer to be acknowledged if I press enter, but I want a chance to try again. | If an incorrect answer is typed in and enter is pressed, the program displays “Try again.”
As a child I want the math facts to be presented to me in a progressive sequence so that the experience doesn’t feel too difficult. | An array of a working problems is built from the first n problems (8–10?) that have not yet been mastered. They are shuffled and presented.
As a child I want to be able to ‘master’ problems so that I can move on to more challenging ones. | When a problem has been answered correctly within 5 seconds two times, mark it ‘mastered’.
As a child I want ‘mastered’ problems to be occasionally reviewed so that I don’t forget them. | Select a ‘mastered’ problems to include in the set of practice problems for each period.
As a child I want practice periods that are not too long (3–5 min?), so that I can focus but not get too tired. | When a practice period begins, a timer is started.( 4 min for now, and then test with children.) After that time, the period ends when the current problem is answered correctly.
As a child I want to see how I did after each period so that I get feedback.
As a child I want some manipulative elements to fade in after about 5 seconds of looking at a problem, or after an incorrect answer, so that I have a way to solve it.
As a child I want to be able to select additional facts to practice so that I can move faster if I want to (I might want to avoid being bored / impress my parent / get this done).
As I child I want a navigation bar with links to the starting screen and to my account, so that I always know where to find these things.
As a child I want to be able to log in and log out so that I can access my own data and protect it from others
As a child I want an easy-to-use home screen directing me to log in or sign up so that I can use the app easily.
As a parent I want the home screen to briefly explain what this app is so that I can decide if I’m interested.
As a parent I want a privacy policy linked the home screen so that I feel I can trust this app.
As a parent I want tips on the home screen so that I will succeed in helping my child practice math (pinning to a device, rewards for practicing, write password)
As a child I want to access a table of my daily time and accomplishments so that I can demonstrate my progress and perhaps earn rewards from my parent.
As a child I want rewarding transition animations between problems so that I get immediate reinforcement for my work.
Extra features to possibly add later:
As a child/parent I want password recovery so that I can still use the app if I forget my password (requires adding parent email to account registration, and some way of adding a parent email to current user accounts)
As a parent I want to receive an email when my child signs up so that I can approve the use of the app
As a parent I want the option to withhold my consent so that I have control over my child’s internet use
As a child I want my first name to be used so that the app seems more personal.
As I child/parent I want more math problems to be added so that I can keep progressing
Implementation: Creating ‘Issues’
User stories and acceptance tests are the last things explained in the Agile Planning book, although it does mention that for larger teams, sprints and releases and size estimation might be needed. For my purposes, I feel that I need to do something to translate these stories, which are units of user value, into manageable tasks I can work on. Knowing that I plan to use Rails and Vue.js, I’m going to make a rough outline of the routes, controllers, models, and views that I’ll need, for the sake of having a mental model. Here we go:
Views: practice, login/signup/root, account. The practice view will basically hold a 1-page app where Vue will do most of the work.
Models: I’ll need a Users model with username and password_digest (strings). Each user will also have a problem set. Each problem will have a minuend (number), subtrahend (number) and some way of keeping track of how many times it’s been answered in 5 seconds or less. A mastered (boolean)? A success_times (number), where if it’s 2 it’s considered “mastered” by the front end, and if it’s 4 it won’t be reviewed any more? I think I like that. I’m realizing that I probably don’t actually want a model for individual problems because they aren’t going to be updated individually in the database with separate http requests. I just want to submit one request at the end of each practice period. Eventually I’ll also want a DatedRecords model with a one:many association with each user, which will have a date (datetime), minutes (number), problems_answered (number), and facts_mastered (number).
Routes and Controllers: I know I’ll need some CRUD actions such as get users#new and post users for signup, get session#new and post sessions for login, delete session for logout. I’ll try getting started with get users/:id for my practice view (alias get username), and patch users/:id to save the data with ajax at the end of each period (then render users/:id). Get user/:id/date_records/index (alias get username/account) could be the account page where the time summary of DateRecords is kept.
