355 Requirements analysis and minimum viable UIs [3d]

Many of our clients can't or don't want to design their user interfaces. In the absence of a good UI design, you should always be able to come up with a default. Since the user interface makes up 70% of a typical web application, this is closely related to requirements analysis and cost estimation.

Important

Work on this lesson in builder mode.

Learning goals

• You can turn prose requirements into a data model: extract the nouns, decide which of them become models, and draw an ER diagram with as few tables as necessary.
• You can explain why nouns from the client's domain don't always map to models one-to-one.
• You can design a default user interface when the client has none, by modelling every interaction as CRUD on a resource — index, show and forms — and placing collection-level and record-level actions where users expect them.
• You can explain how roles with different access rights share one set of screens, and why an admin should be able to override every rule.
• You can produce mockups of the key screens and explain how mockups flush out misunderstandings with a client before any code is written.
• You can write user stories for a feature the way we do it in Linear.
• You can present a client with options for an ambiguous requirement and explain their effect on complexity and effort.

Resources

Read what's new to you, skim what's familiar, skip what you already master. Stop when you can meet the learning goals.

Your agent can also generate an overview, a tutorial or an explanation for anything here, tailored to what you already know. Just ask.

• 📘 "New rules for Rails" from Growing Rails Applications in Practice Show archive.org snapshot (in our library) — the CRUD-everything pattern
• 📄 Project management best practices: User stories / issues — how we write issues
• 📄 Linear: Creating issues Show archive.org snapshot — the tool we write them in
• 🎮 dbdiagram.io Show archive.org snapshot — draw ER diagrams from a text notation
• 🎮 Balsamiq Show archive.org snapshot — quick low-fidelity mockups (ask your mentor for an invite to our account)
• 🎮 Free alternatives: Excalidraw Show archive.org snapshot (hand-drawn look, no account), wireframe.cc Show archive.org snapshot (minimal, no account), Penpot Show archive.org snapshot (open-source Figma alternative) or draw.io Show archive.org snapshot

Discuss with your mentor

• Extracting nouns from requirements prose
• Drawing ER diagrams and minimizing boxes
• Why nouns from the client domain do not always map to Ruby models 1:1. E.g. although an "address book contact" and a "user" are both human beings, it's rarely practical to have them share a model or inheritance hierarchy.
• Try to model everything as CRUD (regardless of whether a model is backed by a database or not).
• How to navigate between indexes, show views, forms
• Where to place actions related to a collection of records
• Where to place actions related to a single record
• How to deal with roles that have different access privileges on a shared set of records
• Why you always want an admin to be able to override all the rules from the requirements and edit records freely.
• How mockups are a great way to flush out misunderstandings and wrong expectations between you and your client.

Exercises

Lemonade Empire

Here is some requirements prose for an imaginary client application.

• Your client runs an empire of 75 lemonade stands.
• Each lemonade stand has a name and address.
• Each lemonade stand is operated by one or more lemonade salespeople.
• At one point in time, a salesperson will only operate one stand. However, salespeople may change their stand.
• Every week, a lemonade stand needs to report the number of lemonades sold this week. Every salesperson can hand in this report for the entire stand.
• Each salesman has their own commission rate (cents per lemonade sold).
• There should be a search functionality to quickly find a lemonade stand or salesperson.
• Once a month, the client should be able to see a report of
  • the sales of each lemonade stand
  • the total commission she needs to pay to each salesperson.
• For the purpose of commission calculation, the number of lemonades sold is distributed evenly among all the salespeople that work for a particular stand.

Please prepare the following deliverables:

1. An ER diagram of the models involved.
   • You can use any tool, for example this one Show archive.org snapshot
2. Mockups for the key screens of this application.
   • You can use paper or any mockup tool you like.
   • Balsamiq (ask your mentor for an invite) or one of the free tools from the resources — Excalidraw is the fastest to start with.
3. User stories in Linear for the following features:
   • CRUD for stands
   • Everything related to viewing and editing weekly reports
   • Read Project management best practices: Issues on how we write user stories. Note that in practice we would do the estimation and wait for customer feedback before creating user stories.

After each step, have your mentor review your deliverable before you proceed. We will practice cost estimation in a later lesson.

Some hints

• Try to not create a UI that has edge cases
• When clarifying a requirement with your customer (here: your mentor), always present the customer with multiple options and explain their effect on complexity and implementation effort.
• Do you store or live-generate the monthly report?
  • What are the pros and cons?
  • What happens if lemonade stand report hand-in happens late?
  • What happens if the commission of a sales person changes in the middle of the year? Does this change past monthly reports? How can we fix this?