Before writing code: clarifying decisions in Mentorual

01Why before code

Mentorual brings mentoring, availability, appointments and institution management into one product. There are mentor, member, institution and administrator roles, and the experience spans web, mobile and administration. My role in this project is product analysis, requirements and design preparation. The work is currently in the analysis and design preparation stage, so there is no codebase I can talk about. What I can talk about are the decisions that need to be made before code is written, and why they carry so much weight.

A product with multiple roles and institutions needs the same action to behave consistently across different screens. If questions like how an appointment looks from the mentor's side, which states it passes through on the member's side and where the institution comes into it stay unanswered, everyone has to answer them on their own during development. In my view this is the most common source of inconsistency in products: not bad code, but decisions that were never discussed.

02From requirement to screen family

The parts of the preparation package are requirements, use cases, screen families and role-permission analysis. It is easy to think of them as separate documents, but the real value lies in the links between them. A requirement should appear in at least one use case, each use case should live on specific screens, and each screen should connect to the question of who can see and do what. When a link in this chain breaks, you end up with either work that never gets done or a screen nobody asked for.

This is why I find the idea of a screen family useful. Instead of listing screens one by one, thinking about the ones that share similar behavior together lets you make recurring decisions once. When patterns like list, detail, form and confirmation repeat across roles, the behavior is expected to stay the same. Web and mobile may present the same family at different sizes, but the rule should stay the same.

requirement
  -> use case
    -> screen family (web / mobile / administration)
      -> role-permission row
        -> acceptance condition

03A role-permission matrix is a contract, not a table

At first glance a role-permission matrix looks like a table with roles as rows and actions as columns. I see it more as a contract: the single answer to “who can do what” shared by analysis, design and development. In a structure with roles such as mentor, member, institution and administrator, that answer needs to be reflected the same way in screens, services and tests.

When thinking through the matrix, the most useful question for me is “in which state is this action in whose hands”. Permission often depends not only on the role but also on the state of the record and the institution context. Writing these distinctions down early cuts off, before it starts, the later debate about why one screen shows a button and another does not.

It is hard to build a workflow correctly without knowing where it ends.

04Separating the MVP from later releases

In this work the MVP and subsequent-release scopes have been separated. This split looks simple on paper but is actually one of the hardest decisions. Every feature seems important; the real question is whether the first release is a meaningful product on its own. The measure I use for this kind of split is: what is the shortest path a role needs to complete its core task from start to finish, and can everything outside that path move to a later release?

The split also has an invisible side. A feature left for a later release is not forgotten; the first release's workflows need to be thought through in a way that does not make that feature harder to add later. Leaving something out of scope does not mean not thinking about it at all.

05Recording decisions

The least visible but, in my view, most lasting part of the preparation package is recording product decisions. Why a decision was made matters as much as what it is. When someone asks “why is it like this” months later, having the answer in a written record rather than in someone's memory prevents the same discussion from happening again and again.

Acceptance conditions are an extension of that record. Connecting the MVP scope, screen requirements and acceptance conditions means defining in advance what counts as “done”. Once development starts, these criteria give both the person implementing and the person reviewing a shared language.

06Analysis is part of building

The idea I keep returning to in this project is that clarifying a product is part of building it. A stage without code is easily dismissed as “preparation”. Yet the answers to who can perform an action, how a workflow ends and exactly what the first release includes determine most of the code that will be written. Development that starts without those answers has to answer the same questions somewhere more expensive.