- Read Tutorial
Requirements Document Flow
This section of the document is going to be the most explicit in regard to describing features. By definition functional requirements list the ‘functions’ of the application.
Since we’re going to be using BDD to build the project, theoretically if we build out a comprehensive list of functional requirements we should be able to directly transfer the requirements to RSpec tests, and then transfer those into implementation code. Easy right? I wish it was as simple as that, in a perfect world the process would flow that way, however even with a great product team and comprehensive requirements complications will still arise as we start to build the application.
Before we list out the functional requirements it’s important to review a brief history of software engineering.
Waterfall vs Agile
In the early days of software engineering, programmers and project managers utilized a project management technique called the Waterfall approach. As with a real world waterfall, the project team would compile a comprehensive list of requirements, attempting to list any and every feature of the software. After the list was complete they’d hand the requirements off to the development team who would then go and build the project to match the complete set of specs.
This waterfall approach failed miserably. In fact it failed so miserably that project management thought leaders have essentially removed the term from their vocabulary. So why didn’t it work? The main issue stemmed from the fact that projects constantly change and the waterfall technique didn’t make room for changes to the features of the project.
The agile approach to software management was born out of the need for projects to entail flexibility in their overall design. Instead of creating a comprehensive list of requirements for the entire application in one swoop, agile project management teaches teams to create small, functional iterations, with each iteration usually lasting no more than two weeks. An example of an agile iteration would be: “In 2 weeks we will integrate a notification system for the application”. Nested inside of that description would be a list of the requirements in order for that feature to be considered complete. Example would be:
- A user should be sent an SMS message after her post received
- A user should be able to manage her notification settings
- A user should have a phone attribute associate with her account
Notice how the requirements are in plain English and explicitly describe the functionality of the feature? Good requirements should clearly describe what needs to be built, leaving no room for ambiguity.
DailySmarty Requirements
In following Agile project management methodologies, we’re going to build out only the initial requirements for our first iteration. Agile approaches seem to differ project manager to project manager, however I’ve seen the most success by organizing the requirements by actor. In this case an actor can be a type of user (student, admin, etc), or a system component (mailer, post, topic, etc). I would say that I would organize the requirements by model, however that would not be specific enough since a user can be both an admin and a student.
Lastly, since we already have our initial database configuration we don’t need to list out requirements such as “student should have a username” since the database schema already lists that out and adding it here would be a waste of time. We will however incorporate which fields are required, which ones should have default values, and any other specific attribute requirements.
User (student role)
- student should have a full_name method that returns her concatenated full name
- student should be associated with a post she creates
- student should be able to edit a post she created
- student should not be able to edit a post she did not create
- student should be able to delete a post she created
- student should not be able to delete a post she did not create
- student should not be able to create topics
- student should be able to like posts
- student should be able to comment on a post
User (admin role)
- admin should be able to delete any posts
- admin should be able to create new topics
- admin should be able to edit topics
User model
- user should be required to have a first name, last name, role, and username
- user role attribute should default to ‘student’ when created
- user should be able to register
- user should be able to sign in
- user should be able to delete her account
- user should be able to edit her account details
- user should not be able to edit her role
- user username should be a sub domain
- user username should be unique
- user username should not allow for special characters
Post
- post should be able to be created if valid
- post should require a title, topic and content to be valid
- post form should not be shown to a user unless signed in
- post should not show an edit form to anyone besides the post creator
- post should allow for rich text formatting
- post should have the ability to have many comments
- post should have the ability to have many likes
- post should be nested under a topic
- post should have a unique permalink including the date and title
Topic
- topic should have the ability to have many posts nested under it
- topic should be able to be created if valid
- topic form pages should only be shown to admin users
- topic name should be its permalink
- topic name should be unique
- topic name should not allow special characters
- topic show page should show all nested posts
- topic show page should Paginate nested posts with 10 on each page
Student Statistics
- stat page should show each topic a user has created a post for
- stat page should show the total number of posts created by the student for each topic
- stat page should show the total number of hours spent studying per topic
It’s looking like it's going to be a pretty cool application. Notice that our requirements didn’t mention features such as: billing, complex learning metrics, admin dashboards, or features such as that. This is because we’re following the agile methodology and we need to make sure we can complete 100% of the features listed in the iteration time range. I think this will give us a great minimum viable product and a solid base where we can start building more advanced features in the future.
Lastly, notice that this is going to be a single application, after reviewing the requirements it makes sense to keep each of the features encapsulated as a single application, as we build out more complex features such as the statistics engine it may make sense to turn certain features into micro services so we can delegate their work to separate apps and servers, but for now I like the app architecture and I’m excited to start building the system!