{"title":"Documenting Projects","description":null,"content":"A hiring manager is unlikely to study your project for an hour. Most will open the repo, skim the README, look at the demo or screenshots, and decide whether the project deserves more attention.\n\nThat is why documentation matters. It helps the reader understand what you built, why it exists, how it works, and what choices you made. A strong project can be overlooked if the README is confusing. A smaller project can make a good impression when the evidence is easy to find.\n\nGood documentation is not a long manual. For a portfolio project, good documentation gives a busy reviewer the shortest clear path to understand and try the project.\n\n---\n\n# What Good Documentation Answers\n\nFor most portfolio projects, the README should answer five questions:\n\n- What does this project do?\n- Who is it for?\n- What is the most interesting technical part?\n- How is it structured?\n- How can someone run it or view it?\n\nA useful README usually includes a clear title, a one-line description, a screenshot or demo, a short explanation of what the project does, the main technical choices, and setup instructions that actually work.\n\nOrdered from top to bottom, a strong README leads the reader from purpose to proof.\n\n\n```mermaid\nflowchart TD\n A[Title +
one-line purpose]:::start --> B[Screenshot
or demo link]:::main\n B --> C[What it does
and who for]:::sec\n C --> D[Design decisions]:::teal\n D --> E[Setup that
actually works]:::good\n classDef start fill:#00ceff,stroke:#000,color:#000\n classDef main fill:#ffa94d,stroke:#000,color:#000\n classDef sec fill:#3bc9db,stroke:#000,color:#000\n classDef teal fill:#38d9a9,stroke:#000,color:#000\n classDef good fill:#69db7c,stroke:#000,color:#000\n```\n\n\nThe order matters because reviewers read top to bottom and stop early. Purpose and a visual come first, the decisions that show judgment come next, and tested setup instructions come last so anyone who wants to run it can.\n\nYou do not need to document every file. You need to help the reviewer answer a simple question: \"What did this person build, and what judgment did they show?\"\n\n---\n\n# Building the README\n\n### Start with a clear one-line description\n\nPut the plain-English purpose near the top of the README.\n\nThis is clear:\n\n\n```javascript\nUpload images and get optimized thumbnails back without waiting for\nprocessing to finish.\n```\n\n\nThis is weaker:\n\n\n```javascript\nA full-stack image processing application built with Node, Redis, and Postgres.\n```\n\n\nThe stack matters, but it should not be the first thing the reader has to understand. Start with what the project does for someone. Mention the tools after that.\n\n### Add a screenshot or demo near the top\n\nIf the project has a user interface, show it. A screenshot helps the reader understand the project before running anything.\n\nFor a workflow with several steps, a short demo clip can help. Keep it focused on the main action. A long walkthrough usually asks too much from a first-time reviewer.\n\nFor a command-line tool, show a short terminal example instead:\n\n\n```javascript\n$ log-tail errors.log --level error --since 10m\nFound 43 errors across 7 services.\n```\n\n\n### Add an architecture diagram when there are moving parts\n\nIf your project has a frontend, backend, database, queue, worker, third-party API, or storage service, include a small diagram that shows how the main pieces connect.\n\nKeep it simple. A good README diagram is not a map of every file or class. It is a quick picture of the system.\n\nMermaid is a good choice because it works in GitHub Markdown and stays in version control. Excalidraw or draw.io are also fine if you prefer drawing visually. Use the tool you will actually maintain.\n\n### Explain the decisions that mattered\n\nAdd a short section called \"Design decisions,\" \"Technical notes,\" or something similar. Include two or three choices that show how you thought through the project.\n\nUseful decisions to explain include:\n\n- Why you used a background job instead of doing slow work during a request\n- Why you chose one data model over another\n- How you handled failures from an external API\n- What trade-off you made to keep the first version small\n- How you tested the most important logic\n\nDo not list every package you installed. Focus on decisions that changed the behavior, reliability, performance, security, or user experience of the project.\n\n### Write setup instructions and test them\n\nA README loses trust quickly when the setup instructions do not work.\n\nClone the repo into a fresh folder and follow your own instructions exactly. If a step is missing, add it. If an environment variable is required, document it. If Postgres, Redis, or another service must be running, say so clearly.\n\nFor a beginner project, setup does not need to be fancy. It needs to be honest and repeatable.\n\n### Add \"What I learned\" only if it is specific\n\nThis section can help early-career candidates, but only when it says something concrete.\n\nWeak:\n\n\n```javascript\nI learned a lot about full-stack development.\n```\n\n\nBetter:\n\n\n```javascript\nI learned why image processing should not happen inside the upload request.\nMoving it to a background worker made the response faster and made failed\njobs easier to retry.\n```\n\n\nSpecific learning shows judgment. Generic learning is easy to ignore.\n\n### Run the five-minute reader test\n\nRead the README as if you had never seen the project. In five minutes, can you answer these questions?\n\n- What does it do?\n- Why does it exist?\n- What is the most interesting technical part?\n- How is it structured?\n- How would I try it?\n\nIf the answer is no, the fix is usually near the top of the README: a clearer description, a better screenshot, a missing diagram, or incomplete setup steps.\n\n---\n\n# A Simple Design-Decision Note\n\nYou do not need a formal engineering document for a portfolio project. A short note like this is often enough.\n\n\n```javascript\n## Why thumbnail generation runs in a background worker\n\nContext: image uploads trigger thumbnail generation, which usually takes\n2-4 seconds. Doing that work during the upload request made the user wait\nfor processing to finish.\n\nDecision: the API stores the image, queues a thumbnail job, and returns a\nresponse immediately. A worker processes the job in the background.\n\nTrade-off: uploads feel faster and failed jobs can be retried, but the\nproject now needs a queue and users may wait briefly before thumbnails\nappear.\n```\n\n\n**Why it works:** The note explains the problem, the choice, and the trade-off. That gives a hiring manager evidence of judgment, not just a list of features.\n\n---\n\n# Architecture Diagram\n\nFor a backend or full-stack project, a small architecture diagram can help a reviewer understand the system quickly. This example shows an upload-and-process flow.\n\n\n```mermaid\nflowchart LR\n A[Browser]:::start --> B[API server]:::main\n B --> C[(Postgres)]:::db\n B --> D[Redis queue]:::support\n D --> E[Worker]:::main\n E --> F[(Object storage)]:::db\n\n classDef start fill:#00ceff,stroke:#000,color:#000\n classDef main fill:#ffa94d,stroke:#000,color:#000\n classDef support fill:#38d9a9,stroke:#000,color:#000\n classDef db fill:#69db7c,stroke:#000,color:#000\n```\n\n\nThis diagram tells the reader that uploads go to an API, metadata is stored in a database, slow work goes to a queue, a worker processes it, and files are stored separately. That is enough for a README. The code can provide the details after the reader understands the shape.\n\n---\n\n# Weak vs Strong READMEs\n\nThe difference between weak and strong documentation is usually clarity. The stronger version does not need to be long. It needs to answer the questions a reviewer has first.\n\n**Weak:**\n\n\n```javascript\n# image-service\n\nA service for uploading and processing images.\n\n## Setup\nnpm install, then npm start. Make sure Redis and Postgres are running.\n```\n\n\nThis leaves too much work for the reader. They do not know who the project helps, why Redis is there, how the pieces connect, or what decision is worth noticing.\n\n**Stronger:**\n\n\n```javascript\n# image-service\n\nUpload images and get optimized thumbnails back without waiting for\nprocessing to finish.\n\n[screenshot of the upload UI]\n[architecture diagram]\n\n## What it does\nUsers upload images through the web UI. The API stores the original image,\nadds a thumbnail job to a queue, and returns immediately. A worker creates\nthe thumbnails and stores them separately.\n\n## Design decisions\n- Background worker for thumbnail generation\n- Postgres for image metadata\n- Object storage for original images and generated thumbnails\n\n## Running it locally\n[tested clone, environment setup, database setup, and run commands]\n```\n\n\n**Why it works:** A hiring manager can understand the purpose, see the system shape, and notice the important technical decision without reading the entire codebase.\n\n---\n\n# Documentation Mistakes to Avoid\n\nA reviewer spends about a minute on your README before deciding whether to clone the repo, and a thin one wastes that minute.\n\n- **Writing only a one-line README.** A short description is not enough when the project has a setup process, technical decisions, and a real problem behind it.\n- **Listing features but not decisions.** Features show what the project does. Decisions show how you think.\n- **Skipping the diagram on a project with moving parts.** If there is a frontend, backend, database, queue, or external service, a simple diagram can save the reader time.\n- **Making the diagram too detailed.** A diagram with every file, class, and endpoint becomes hard to read. Show the main components and the flow between them.\n- **Leaving setup instructions untested.** Broken setup makes the project look unfinished, even if the code works on your machine.\n- **Using a long demo clip.** A short clip of the core action is enough. Long walkthroughs are rarely watched carefully.\n- **Assuming the reader will inspect the code to understand the project.** Most reviewers skim first. The README should make the project worth a closer look.\n\n---\n\n# What To Do Next\n\nOpen the README for one project you want to show. Make sure the first screen answers three questions: what the project does, who it helps, and why it is technically interesting.\n\nThen test the setup instructions from a fresh clone. If a reviewer cannot run or understand the project without guessing, fix the README before you put the project on your resume.","pageType":"job-search"}

Get Premium