Ship It: Deploy, Document and Make Your GitHub Easy to Read

A recruiter opens your GitHub profile. They see twenty repositories named project1, test, java-practice and final-year-project-new, none with a description, the most recent updated eight months ago. They close the tab. It took them twelve seconds.

Another profile shows a short introduction at the top, four pinned repositories with clear names and one-line descriptions, and the first one has a live demo link. The recruiter clicks it. Now you have their attention.

Nothing about your coding ability changed between those two profiles. Only the packaging did, and the packaging is cheap to fix.

• How to put a student project online for free, and what to watch out for.
• A README structure that answers a reviewer's questions in a minute.
• How to add an architecture diagram with Mermaid, which GitHub renders directly.
• How to keep secrets out of your repository.
• How to set up your GitHub profile so it leads with your best work.

A repository without a live link says "I wrote some code". A link that loads says "I built something that runs". Many reviewers will never clone your repository and install dependencies to try it. They will click a link.

Most student projects fit into a few kinds of hosting, each with free tiers:

Three practical points:

• Sleeping services. Many free backend tiers stop your service when nobody uses it and take some seconds to wake up. That is fine for a portfolio, but say so in the README ("the first request may take up to a minute while the free server starts"), or a reviewer may think it is broken.
• Expiring databases. Some free databases expire or pause after a period. Put a reminder in your calendar to check that your demo still works before every application week.
• Seed data. A demo with an empty database shows nothing. Add sample data, and if login is needed, provide a demo account in the README (with no real personal data).

• The link loads in a normal browser, logged out, on mobile data.
• A visitor can do the main thing within a minute, with sample data or a demo login.
• Errors show a sensible message, not a stack trace.
• No secrets are visible in the page source or in error messages.
• The README says how long the first load might take.

A reviewer opening your repository wants to know five things, in this order. Structure your README to answer them.

# Project nameOne sentence: what it is and who it is for.Live demo: <link>   (first load may take ~1 minute on the free tier)Demo login: demo@example.com / demo1234   (sample data only)## Why I built itTwo or three sentences: the problem, and why it interested you.## What it does- Feature 1- Feature 2- Feature 3A screenshot or short GIF.## How it worksA short architecture diagram (see below) and one paragraph on the flow.## The hard partThe one interesting problem and how you solved it. Link to DECISIONS.md.## ResultsWhat you measured, how, and the numbers (article 10).## Run it locallyExact commands, from clone to running, including how to set environment variables.## What I would do nextTwo or three honest improvements.

The "hard part", "results" and "what I would do next" sections are what separate a portfolio README from a homework submission. They also tell an interviewer exactly what to ask you about.

An assistant writes a decent first README if you feed it facts. Without facts it fills the gaps with impressive-sounding claims.

Draft a README for my project using ONLY the facts below.Follow this structure: [paste the structure above].Where a section has no facts from me, write "[to fill]" instead of inventing.Keep it plain and specific; no words like "robust", "seamless", "cutting-edge"or "scalable" unless I gave a measurement that supports them.Facts:- What it is: ...- Why I built it: ...- Features: ...- Stack and deployment: ...- The hard part and my solution: ...- Measurements: ...- How to run locally: ...

Then read every sentence and check it is true. Fill each "[to fill]" yourself or delete the section.

A diagram lets a reviewer understand your system in seconds. GitHub renders Mermaid diagrams written inside a fenced code block marked mermaid, so you need no drawing tool. For example:

flowchart LR    Client[Web client] -->|HTTPS JSON| API[Spring Boot API]    API -->|SQL| DB[(PostgreSQL)]    API -->|enqueue| Q[Retry queue]    Q -->|process| Worker[Payment worker]    Worker -->|calls| Provider[Simulated payment provider]    Worker -->|webhook| Merchant[Merchant endpoint]

Label the arrows with what flows along them. Keep it to the components that exist. A diagram showing a load balancer and a cache your project does not have will be noticed.

An assistant can draft the Mermaid code from a plain description:

Write a Mermaid flowchart (flowchart LR) for this architecture. Include onlythese components and connections, with labels on the arrows:[describe: what talks to what, and what data flows]

Paste it into your README and view the page on GitHub to check it renders correctly.

This is the most common serious mistake in student repositories. Passwords, API keys, database connection strings and cloud credentials committed to a public repository can be found by automated scanners quickly, and can be misused to run up bills or access your data.

• Put secrets in environment variables. Locally, keep them in a .env file, and list .env in .gitignore before your first commit.
• Commit a .env.example file with the variable names and fake values, so others know what to set.
• Set the real values in your hosting provider's settings, not in code.
• If you ever committed a secret, revoke it and create a new one. Deleting the file in a later commit does not remove it from the repository's history.

GitHub also has secret-scanning features that can warn you about some kinds of exposed keys, but do not rely on them as your only protection.

If you create a public repository with exactly the same name as your GitHub username and add a README.md to it, GitHub shows that README at the top of your profile page. Use it for a short introduction:

Hi, I'm [Name]. I build backend services in Java and Spring Boot.Currently building: [project], a payment service with safe retries. [link]Projects- [Project 1]: one line, live demo link- [Project 2]: one line, linkContact: [LinkedIn] · [email]

Keep it short and factual. Badges and animated graphics are optional; a clear sentence about what you build is not.

You can pin up to six repositories to your profile. Pin deliberately:

1. Your strongest complete project (with a live demo).
2. Your second-best project.
3. A contribution to someone else's project, if you have one (article 9).
4. Anything small but well made: a tool, a library, a solved problem set with good notes.

Fewer, better pins beat six weak ones.

For every pinned repository:

• A clear, specific name (payment-retry-service, not project2).
• A one-line description in the repository's "About" box, plus the live link in its website field.
• A few topics (for example spring-boot, payments, idempotency), which make it easier to find.
• A README following the structure above.
• A licence file if you want others to be able to reuse the code (MIT is a common simple choice).
• Meaningful commit messages ("Add idempotency key check on payment creation", not "changes").

The green squares show when you committed. Regular activity on real work signals that you keep building, and it happens naturally while you work on a project. Do not manufacture it: scripts that create empty daily commits, or meaningless changes made just to turn squares green, are easy to recognise when someone opens the commits, and they undermine everything else on the profile.

Rohan's profile before: 17 repositories, mostly unnamed course exercises, no profile README, one real project called mini-proj with no README and a database password in application.properties.

After one weekend:

1. Revoked the database password, created a new one, moved it to an environment variable, added .env to .gitignore.
2. Renamed mini-proj to campus-events-api, deployed the backend on a free application platform and the database on a free PostgreSQL tier, added sample events.
3. Wrote the README with the five-question structure and a Mermaid diagram, noting the slow first load.
4. Made the course-exercise repositories private, created a profile README, pinned three repositories.

His code did not change, except to remove the secret. A recruiter now sees a clear, working project in seconds.

• Deploying in the last week, then running out of time when the free tier behaves unexpectedly.
• A README that is only "npm install, npm start". It answers none of the reviewer's questions.
• Committed secrets, including in old commits.
• A diagram of an imaginary architecture. Draw what exists.
• Faking activity. Real work leaves real commits.

# Expense TrackerTrack shared expenses in a hostel room and see who owes whom.Live demo: <link>  (first load can take up to a minute on the free tier)Demo login: demo@example.com / demo1234 (sample data only)## Why I built itSplitting bills among four roommates in a spreadsheet kept going wrong.I wanted settlements that need the fewest payments.## What it does- Add expenses split equally or by share- See balances per person- Get a settlement plan with the minimum number of payments[screenshot]## How it works[Mermaid diagram: React client -> Express API -> MongoDB]The API stores expenses and computes balances on request.## The hard partMinimising the number of settlement payments. I used a greedy approach thatmatches the largest debtor with the largest creditor; see DECISIONS.md forwhy, and the case where it is not optimal.## Results[measured response time for balance calculation with 1,000 expenses, and howit was measured]## Run it locallygit clone ... ; cd ... ; cp .env.example .env ; npm install ; npm start## What I would do nextRecurring expenses; export to CSV; tests for rounding with uneven splits.

• Next: External Proof: Open Source, Hackathons and Writing About Your Work adds the signal that someone other than you values your work.
• For a portfolio website that brings your projects together, see How to Build a Developer Portfolio Website That Gets You Interviews.
• For keeping data and keys safe when you use AI tools, see Privacy and Security: What Not to Paste, Connected Tools and Prompt Injection.