Project Brief Essentials
Project scoping means defining a project tightly enough to start working on it.
Why Starting With the Editor Is Risky
Most people want to begin a project by opening an editor and writing the first function. The urge is understandable, but it skips a question that decides whether the work will go anywhere: how tightly is the project defined? A project can have a clear name and still be too vague to act on. Project scoping is the process of defining a project tightly enough that you can start working on it. This article looks at one practical tool for that job, the project brief, and at how the act of writing it becomes part of the work itself.
What do you think happens?
You have a project name and a rough idea. What should you settle before writing the first function?
Reveal answer
How tightly the project is defined
The source says that a project can have a clear name and still be too vague to act on, so scoping comes before coding. Defining the scope tightly enough to start is the decision that determines whether the work will go anywhere.
The Five Sections as Questions
The project brief is built around five sections: the customer, the proposed system, the eval set, the first slice, and the success metric. The source presents these as a structure you should adopt as your own template, so you do not need to invent a new format each time. Each section answers a different question about the project, and together they turn a loose idea into something you can check.
- Customer: Who is the customer?
- Proposed system: What is the proposed system?
- Eval set: What is the eval set that will be used to check it?
- First slice: What is the first slice you will build?
- Success metric: What is the success metric?
Read the five sections as a set of questions rather than a form to fill out. The section names come from the source, and the distinctions between them matter. Each one forces a different decision, so a brief that leaves one of them blank has a gap that the others cannot cover.
Eval Set Versus Success Metric
Two of the five sections are easy to confuse: the eval set and the success metric. The source states that they are not the same thing. The eval set describes what you will check the system against. The success metric describes how you will judge the result. One is the material the system is tested on; the other is the standard by which the test outcome counts as good or bad.
A brief that names an eval set but gives no success metric has said what the system will be checked against, but not what counts as a pass. Keep the two sections separate when you write them.
Applying the Plain-Language Test
The source gives a practical check for whether scoping is finished. Try to fill in all five sections in plain language, without jargon. If you can do that, the project is scoped well enough to begin. If you cannot, the project is not yet scoped tightly enough to start. The test is simple, but it is strict. Jargon often hides gaps. A sentence that sounds technical may be covering up the fact that you have not decided who the customer is or what the first slice contains.
Testing a Vague Brief
A learner writes this customer section for a project: "Customer: people who need help with their finances." Does it pass the plain-language test?
- 1Read the section in plain language
The sentence contains no technical jargon, so it passes the surface check. The source warns that jargon often hides gaps, so passing on wording alone is not enough.
- 2Ask what the sentence actually decides
Who is included in people who need help with their finances? The phrase does not say who the customer is in a way that could guide a decision. It is too broad to settle the question the section asks.
- 3Apply the test as a whole
The test asks whether all five sections can be filled in plainly. The customer section is not yet decided, so the project is not yet scoped tightly enough to start.
- 4Revise and retest
A tighter customer section, such as naming one specific group and the problem it has, gives the learner something they can build against. Then the other four sections are checked the same way.
The brief fails the test. The learner should narrow the customer section and continue checking the remaining sections before starting work.
Ready to Start Versus Too Broad
The contrast below sets a scope that is ready to start against one that is not. The difference is not the project name, which may be identical in both cases. The difference is whether each section makes a decision you could act on. A ready scope lets you state each section plainly; a broad scope leaves the sections open.
The Brief as Part of the Deliverable
The source makes a claim that many learners find surprising: the brief is not just preparation for the project, it is part of the project's deliverable. If you can fill in all five sections in plain language, the brief is itself the first portfolio artifact. The source gives a concrete step for this.
- 1Fill in all five sections of the brief in plain language, without jargon.
- 2Commit the brief to the repository README before you write a single line of code.
- 3Begin the build, using the brief as the scope you are working against.
- 4Revise the brief as the project teaches you what you missed.
Mistakes When Scoping a Project
Common mistake Starting to code before the scope is defined
What it looks likeOpening an editor and writing the first function before deciding who the customer is.
Why it failsThe source says a project can have a clear name and still be too vague to act on, and that the urge to start coding skips the scoping question.
Do this insteadComplete the five sections in plain language, then commit the brief to the repository README before writing code.
Common mistake Treating technical wording as proof of a finished scope
What it looks likeA customer section filled with specialist terms that do not say who the customer actually is.
Why it failsThe source notes that jargon often hides gaps, so a sentence that sounds technical may cover an undecided customer or first slice.
Do this insteadRewrite each section in plain words. If a sentence only works with jargon, the gap is still there.
Common mistake Merging the eval set and the success metric
Why it failsThe source states they are different: the eval set is what you check the system against, and the success metric is how you judge the result.
Do this insteadGive each its own section and answer its own question.
Common mistake Treating the brief as a one-time document
Testing Your Own Brief
Choose a project you are considering. Write one plain-language sentence for each of the five sections: the customer, the proposed system, the eval set, the first slice, and the success metric. Then reread each sentence and mark any word you would need to explain to a non-specialist. If you marked any section as unclear, revise it and check again.
Hints
- Check the customer section first. If you cannot say who it is for without a technical term, the project is not yet scoped.
- Keep the eval set and the success metric in separate sentences, since the source treats them as different things.
- A revised brief is still valid. The source expects you to revise it as the project teaches you what you missed.
Key Takeaways
- Project scoping means defining a project tightly enough that you can start working on it, and the project brief is the practical tool for that job.
- The brief has five sections: the customer, the proposed system, the eval set, the first slice, and the success metric. Each answers a different question, and the eval set and success metric are not the same thing.
- The plain-language test asks whether you can fill in all five sections without jargon. If you cannot, the project is not yet scoped tightly enough to start.
- The brief is part of the deliverable. Commit it to the repository README before writing any code, and revise it as the project teaches you what you missed.