Week one portfolio lab: explain one project decision clearly

This is an evergreen communication exercise

This article is a week-one practice lab, not a claim about a new technology release. The goal is to make one piece of technical reasoning visible. You might explain why a small task tracker stores filters in the URL, why a form validates on both client and server, or why a test uses a stable role-based locator instead of a CSS class.

GitHub describes a repository README as a place to tell people what a project does, why it is useful, how to start it and where to get help. Those basics give a visitor context, but a short decision note adds something different: it shows how you evaluated alternatives instead of only showing the finished screen.

Source: GitHub Docs: About the repository README file

Pick a decision that has a real tradeoff

Avoid inventing a dramatic architecture problem. Look through your first week of commits and choose a decision that changed behaviour, maintainability, accessibility, security or testing. Good beginner examples include choosing server-side validation, keeping state in a query string, separating an API call from a UI component, or adding an index after examining a query.

A useful decision has at least two plausible options. ‘I used JavaScript because the project uses JavaScript’ is background, not much of a decision. ‘I kept the filter in the URL instead of component-only state so a filtered view could be bookmarked, while accepting extra parsing work’ exposes both the benefit and the cost.

Use a compact decision-record structure

Microsoft’s guidance for architecture decision records recommends recording context, options, the outcome, tradeoffs and status. It also warns that rationale matters because a choice without justification becomes difficult to evaluate when circumstances change. Your portfolio note does not need enterprise architecture language, but the same structure works well for a small project.

Write six short headings: Problem, Constraints, Options, Decision, Evidence and Limitation. Keep facts separate from preference. For example, a deadline is a constraint; ‘I prefer this library’ is not evidence. If you had low confidence or incomplete information, say so and describe what result would cause you to reconsider.

Source: Microsoft Azure Well-Architected Framework: Maintain an architecture decision record

Complete the 30-minute decision lab

Open one project you can run locally. Select a completed change and create a short note in the README or a docs/decisions folder. Do not rewrite history to make the first attempt look perfect. The learning value comes from showing what you knew, what you tested and what remains uncertain.

Then ask another learner to read only the note and the relevant diff. Their task is to explain the problem back to you and identify the tradeoff. If they cannot, revise the context before adding more technical detail. A clear explanation should help a reviewer understand the decision without requiring a tour of the entire codebase.

• Problem: describe the user or engineering issue in two sentences.
• Constraints: list the time, compatibility, data or scope boundaries that mattered.
• Options: name at least two approaches and one advantage of each.
• Decision: state what you selected and the tradeoff you accepted.
• Evidence: record a test, measurement, screenshot or reproducible observation.
• Limitation: identify one case not solved and the signal that would trigger a review.

Source: Microsoft Azure Well-Architected Framework: Maintain an architecture decision record

Make the change easy for another person to review

GitHub’s review guidance says clear context should explain why a change is needed, what changed and where a reviewer should pay attention. It also recommends reviewing your own change, checking the diff for accidental edits and confirming that relevant builds or tests ran. Use those habits even when the project has no formal pull request.

Keep the evidence focused. Link to the important file or commit, list the exact command you ran and include the observed result. Do not claim that one passing test proves scalability, security or production readiness. If an AI assistant suggested code or wording, review it against the project and describe your own verification rather than presenting generated output as independent evidence.

Source: GitHub Docs: Helping others review your changes

Turn the note into a two-minute interview answer

Practise speaking through the same sequence: context, two options, choice, evidence and limitation. Stop after two minutes and invite a question. This creates a concrete answer to ‘Tell me about a technical decision’ without exaggerating the size of the project or pretending you worked in a production team.

For a portfolio, keep the runnable project, decision note and validation output together. Learners in Chennai or online can use this lab while exploring SPOTHUB’s Full Stack Development + AI learning path. The exercise demonstrates communication and review habits; it does not guarantee an interview, job or other career outcome.

Sources and further reading

• GitHub Docs: About the repository README file · checked 2026-09-23
• Microsoft Azure Well-Architected Framework: Maintain an architecture decision record · checked 2026-09-23
• GitHub Docs: Helping others review your changes · checked 2026-09-23

Spot an error? Email info@spothub.in with the article link and correction.