Describe an unfinished practice project by stating its current scope first, then separating implemented features, observations, known limitations and possible next steps. A reader should be able to tell what the project does today without mistaking an idea for a working feature or a brief check for comprehensive testing.
An incomplete project can still show how you approach a problem. The useful detail is the boundary: what you built, how you checked it, what you noticed and where your evidence ends. The example below is fictional; its observations illustrate how a learner might document a real project, not results from an actual test.
What should you establish before writing?
Choose a snapshot of the project to describe. Open the version you plan to share and make a short inventory of the behavior it currently supports. For each feature, identify the action a person can take and the result they can see. If a feature exists only as a sketch, an empty screen or an unfinished branch, describe it as planned or partial rather than built.
Next, record how you checked the current version. A manual check might consist of entering three sample tasks, marking one complete and reloading the page. Write down what happened and the conditions of that check. If you have not checked a behavior, say so; absence of evidence is different from a confirmed defect.
Finally, list the boundaries a reader would need before trying or evaluating the project. These might include missing features, a known failure, limited testing or setup steps you have not yet documented. Keep a separate list of ideas for later. This small separation prevents a roadmap from looking like a list of existing capabilities.
GitHub’s README guidance recommends explaining what a project does and how someone can get started. For a practice project, add a clear status and limitations so those instructions do not imply a finished product. If the project cannot currently be run by someone else, say what is missing instead of supplying guessed setup instructions.
What could a concise README look like?
Imagine a fictional learner, Maya, building a small browser-based task list to practice JavaScript. She can add tasks and mark them complete. In her own manual check, the list disappeared when she refreshed the page. She has not implemented storage, editing or deletion, and she has not tested the project across browsers. Her README could read as follows:
Project: Small Task List. Status: Unfinished practice project. Purpose: Practice handling user input and updating a page with JavaScript.
Built so far: Add a task to the displayed list and mark a task as complete during the current page session. The list is held in memory and is not saved.
Observation: In one manual check, I added three sample tasks and marked one complete. The displayed list cleared when I refreshed the page. This check describes that session only; I have not completed broader testing.
Known limitations: Tasks do not persist after a refresh. Editing and deleting tasks are not implemented. I have not checked behavior across browsers or assessed accessibility.
Possible next steps: Add persistent storage, implement deletion, check keyboard use and document how to run the project locally. These are plans, not completed features.
This example gives the reader a usable picture without asking them to infer completion from a project name. In a real README, Maya would also add accurate setup and usage instructions once she had checked them against the shared version. If she could not reproduce an observed behavior, she would describe the uncertainty rather than silently presenting it as a confirmed bug.
How do you distinguish a defensible claim from an inflated one?
A defensible description names a specific action and keeps the claim within what the learner actually did or observed. The examples in this table refer only to Maya’s fictional project; they are not interchangeable claims about every task-list application.
The distinction is especially useful for quality claims. A feature that worked during one manual check may be worth describing, but that observation cannot establish that it works for every input. Similarly, planning to add storage does not mean the existing application saves data.
Topic | Defensible description | Overstated claim
Current functionality | Users can add tasks and mark them complete during the page session. | Built a complete task-management application.
Checking | Manually checked adding three tasks and marking one complete. | Thoroughly tested all task-list features.
Storage | Tasks currently disappear on refresh; persistent storage is a possible next step. | Implemented reliable task storage.
Accessibility | Keyboard use has not yet been assessed. | The application is accessible to everyone.
Scope of work | Built the current interface as a practice project. | Delivered a production-ready product.
How much detail should you give about checks and limitations?
Give enough detail for the reader to understand the evidence, but do not turn every small observation into a testing report. State the action, relevant conditions and observed result. If a check failed, describe the failure plainly and say whether you could reproduce it. If you ran an automated test, name what it covered; avoid implying that it checked the whole application.
Be just as precise with unknowns. “I have not checked keyboard navigation” is different from “keyboard navigation is broken.” The first identifies an untested area; the second asserts a result. If you later investigate and find a problem, update the limitation with the behavior you observed.
Prioritize limitations that could change how someone interprets or uses the project. A missing delete button matters to someone trying a task list; so does data disappearing on refresh. A long list of speculative future enhancements can obscure those facts, so put the most consequential current limits first.
Avoid copying Maya’s checks as though you performed them. Replace every example with your own actions and observations. If you used a tutorial, starter code or another person’s contribution, identify its role and distinguish it from the work you did yourself.
How should the description change for an application?
A README can hold the fuller explanation; an application usually needs a shorter account. Select one or two implemented actions, identify the work as practice and include a meaningful limitation when it prevents the reader from misunderstanding the scope. For Maya’s fictional project, a concise description could be: “Building a JavaScript task list as a practice project; implemented adding and completing tasks, with persistent storage still to do.”
If you want to go further, Talyca has a practical guide to remote job scams in Canada: warning signs to rule out before you apply.
Before sharing, review the project and its description together. Remove claims you cannot trace to the current version, label intentions as intentions, and check that any instructions you provide are accurate. Revisit the README when the project changes: once storage is actually implemented and checked, the old limitation and the new claim should both be updated.
Responses (0)