Planning a project · 4 min read
What to tell a developer before you start a project
Explain what is broken, what you need instead, and how you will check the result. A short project brief can help you agree on the work before spending money.
You do not need to write a technical plan before talking to a developer. Explain the problem, show an example, and say what you want to happen instead. A few clear details help both sides agree on the first piece of work and what it might cost.
What to take away
- Describe the problem before choosing the technology.
- Agree on a small first result and how you will check it.
- Leave time for setup, investigation, testing, and handover.
Show what is getting in the way
“Improve our customer portal” leaves a developer guessing. “Customers email us for copies of their invoices. We want them to download those invoices themselves” explains who needs help and what needs to change. This is an example brief, not a client case study.
For a bug, explain what you clicked, what you expected, and what happened. Include the device or browser if it matters. GitHub issues let a team keep that description and the discussion together. Your existing project tool can serve the same purpose.
Use made-up customer details in examples and remove passwords or private records from screenshots. A clear test case is more useful than a large file of unexplained data.
Sources: GitHub Docs: Creating an issue
Agree on how you will check the work
For the invoice example, a customer should see their own invoices, be unable to see anyone else’s, and get a clear message if they have none. Those are things you can check together before calling the work done.
Think about phones, missing information, repeated clicks, and connected apps being down. Tell the developer which failures would cause trouble for the business. They can turn those concerns into technical tests.
Choose who will approve the result and when they can review it. If several people need a say, collect their requirements before work starts.
- Who should be able to use it?
- What should happen when something is missing or goes wrong?
- What will you click or check before you approve it?
Find out what access the developer needs
List the apps and accounts involved, and who can grant access. Work can stall because nobody can reach the hosting account or approve a connection to the customer system.
An unfamiliar codebase or a bug that appears only sometimes can take time to investigate. Ask what is already known and what needs checking before an estimate is useful. You can agree on a short investigation with a time limit and a written recommendation.
Keep your business in control of the code and service accounts. Give the developer the access the job needs, and agree when to remove it.
Choose hours or a fixed price based on the work
A block of hours can suit a bug hunt or a project where the first findings will shape what happens next. Agree what the developer will tackle first and when they will update you. Buying five hours does not mean an unknown project can be finished in five hours.
A fixed price is easier to agree on when both sides understand what is included. Write down the pages or features, how you will approve them, and how extra requests affect the price.
For a larger project, start with a smaller useful piece. Letting customers view existing invoices could come before adding subscriptions or new payment methods.
Make sure you can use and maintain what you paid for
Agree what you will receive besides a demo. That may include the code in your repository, the change on your live site, setup instructions, and a list of anything still unfinished.
Ask who handles problems after launch, what fixes are included, and how to request new work. For a change to a live system, agree who approves the release and how to undo it if needed.
A brief can fit on one page. Keep it up to date when decisions change so the plan does not get lost across emails and chat messages.
Keep this handy
Your pre-project checklist
- Who has the problem, and what do they need to do?
- Can you show an example without sharing private information?
- What will you check before approving the result?
- Which accounts and apps need access?
- What is outside the first piece of work?
- Who reviews the work, and what happens when the budget runs low?
Prefer to write it down? Tell us about your project. No portal account required.
These examples explain how we would approach the work. They are not client results. How we write our guides or send a correction.