Software · Practical guide
Outgrowing spreadsheets? Write a brief developers can use
Turn scattered approvals, manual updates and reporting problems into clear software requirements.
Describe the daily frustration first
“Build us a dashboard” is a difficult starting point. “Our team spends every morning finding orders that nobody has approved” is much more useful. It identifies a person, a recurring problem and an outcome that software might improve. Start there before making a list of screens.
Collect a few examples from the people who do the work. Note where information is copied, where decisions wait and where mistakes need to be corrected. Use anonymised samples, and separate a problem the team experiences today from a feature that simply sounds interesting.
Describe the workflow before the features
Start with a process your team already performs: receiving an order, approving a purchase or reconciling stock. Document what starts it, who participates, what information moves between people and how it finishes. Include the awkward cases, not just the happy path.
A request for a dashboard describes a screen. A requirement to show overdue approvals to the responsible manager describes a business need. Use needs like this to decide which screens and notifications are actually necessary.
Map roles and permissions
List the people who create, review, approve, edit and export information. Write down which records each role can access and which actions need approval. Do not assume that hiding a button is enough to enforce a permission; include server-side checks in the acceptance scope.
For a purchase process, a requester might draft an order, a manager might approve it and finance might record payment. Decide what happens when the manager is absent, an order changes after approval or a payment is reversed. These exceptions influence both implementation and testing.
Inventory the data and integrations
Identify where the current data lives, who owns it and which fields are reliable. Before migration, agree on duplicate handling, required fields, old records and a sample import. Use anonymised examples during planning rather than sharing complete customer databases.
For each integration, record the source system, direction of data flow, frequency and failure behaviour. Ask what happens when the external service is unavailable or sends a duplicate event. Decide who resolves mismatches and how the system exposes them to the team.
Turn requirements into acceptance checks
Replace broad phrases such as “easy to use” or “fully automated” with observable outcomes. For example: an authorised approver can approve a request; a requester cannot approve their own request if that is the policy; and an approval records the actor and time.
Cover invalid inputs, missing permissions, interrupted connections, duplicate submissions and recovery after failure. Use a written test list that both the delivery team and the business owner can understand. Prioritise the workflows whose failure would stop operations.
Plan the rollout and handover
Choose whether to migrate everyone at once or start with a small team. Define how you will verify migrated records and what you will do if the new workflow cannot be used. Name the person responsible for business acceptance rather than leaving approval implicit.
Agree access to repositories, deployment instructions, backups, operational documentation and support contacts. Clarify which components are custom work and which depend on third-party licences. Ask how updates are delivered and how the team exports its data if the arrangement ends.
Bring a concise brief to the first discussion
Prepare a process map, role list, sample non-sensitive records, integration inventory, essential reports and the most common exceptions. Mark requirements by operational importance and identify any fixed deadlines with their reasons.
The result should be a shared understanding of the first useful release, not a promise to automate everything immediately. Code Bro can help turn this information into a scoped software proposal with explicit deliverables, assumptions and acceptance criteria.