{"course":{"slug":"ai-careers","title":"Working in AI","url":"https://addaly.com/learn/ai-careers","level":"beginner","track":"work"},"lesson":{"slug":"the-case-study-page","title":"Writing up a project as a decision record","url":"https://addaly.com/learn/ai-careers/the-case-study-page","position":31,"of":85,"minutes":8,"answer":"Write the project as a record of decisions (the mess, the choice, the number, and what it still gets wrong) because that is what a reviewer is reading for.","keyIdea":"Write the project as a record of decisions (the mess, the choice, the number, and what it still gets wrong) because that is what a reviewer is reading for."},"body":{"format":"markdown","text":"## The ninety-second reading order\n\nA reviewer opens your project page and reads in this order: the title, the first sentence, whatever number is visible, and then, if you have earned it, the section admitting what is wrong. They almost never read the code.\n\nSo write for that order. Everything that proves something goes above the fold, and the honest limitations go near the top rather than buried at the bottom, because their presence is itself the strongest signal on the page.\n\n## The template\n\n```\n# Bus delay tracker — Lagos, route 57\n\nTells a transport cooperative's dispatchers which departure\nwindow runs late most often. Updated nightly.\n\n**Used by** 6 dispatchers, weekly, since March 2026.\n\n## The mess\nThree of eleven months had GPS timestamps recorded in local\ntime and eight in UTC, with nothing labelling which. I found\nit because \"delays\" spiked by exactly one hour on the day the\ndevice firmware changed.\n\n## Two decisions\n- Dropped the first two weeks entirely rather than\n  interpolating. The device swap meant I could not tell\n  which clock any reading came from, and inventing a\n  correction would have hidden that.\n- Median rather than mean. Two breakdowns of four hours\n  each were dragging every weekly average upward.\n\n## Does it work\nI wrote 30 test journeys with known outcomes from the\ndispatchers' own paper log. It classifies 27 correctly.\nOf the 3 misses, all are journeys crossing midnight.\n\n## What it gets wrong\nNo handling of public holidays — a dispatcher found this\nbefore I did. Midnight-crossing journeys, as above.\n\n## Run it\n`make dev`, then open localhost:8000. Sample data included.\n```\n\nThat page takes ninety minutes to write and outperforms three more projects.\n\n## Why each section is there\n\n**The mess and how you found it.** This is the only part of the page that cannot be faked by copying a tutorial. The detail that you noticed the spike was *exactly* one hour is worth more than any architecture description, because it shows how you think when something is wrong.\n\n**Two decisions, with the rejected alternative.** A decision with no discarded option is not a decision. Naming what you did not do is what distinguishes judgement from following instructions.\n\n> Figure: The page, in the order a reviewer reads it. Layers, top to bottom: Title and first sentence: what it does, for whom, how often (read by everyone); Used by: a real count, with dates (the visible number); The mess, and exactly how you found it (the part a tutorial cannot fake); Two decisions, each with the alternative you rejected (judgement, not instructions); Does it work: thirty cases and a count (27 of 30, and what the misses share); What it gets wrong (raises credibility on everything above it); Run it: one command (a project that does not run is not evidence). Ninety seconds: the title, the first sentence, whatever number is visible, then the section admitting what is wrong. They almost never read the code, which is why the mess and the number sit above it.\n\n**A number.** From the previous lesson. Thirty test cases and a count. Most beginner portfolios contain no number at all, and the ones that do stand out immediately.\n\n**What it gets wrong.** Counter-intuitive and true: admitting a limitation raises your credibility on everything else on the page, because it tells the reader you know how to look for problems. A page with no limitations reads as a page written by someone who has not checked.\n\n## Publishing work you did for someone else\n\nIf the project was for a client or an employer, you cannot simply publish it.\n\n- **Ask, in writing, before you publish anything.** An email saying \"may I write publicly about the approach, with your name and figures removed?\" is usually answered yes, and it protects you.\n- **Never publish their data.** Not a sample, not an anonymised extract, not \"just the schema\" if the schema is distinctive.\n- **Replace real figures with realistic invented ones and say so.** \"Figures changed for confidentiality; proportions preserved\" is honest and reviewers accept it.\n- **A blurred screenshot is not anonymisation.** The underlying CSV may still be in your repository, and blur can sometimes be reversed. Regenerate the screenshot with fake data instead.\n- **If you cannot publish it at all**, write a page about the *problem shape* with no client details. \"How I found a timezone bug in a delivery dataset\" needs no client name.\n\n## Show it moving\n\nA forty-second screen recording of the thing working outperforms three paragraphs, because it proves the project exists in a way a repository does not. Free tools do this: **OBS Studio** on any platform, the built-in recorder on macOS and Windows, **Peek** on Linux. Loom is the paid product people reach for; nothing about a forty-second clip needs it.\n\nKeep it short and unnarrated. Nobody watches minute two.\n\n## The mistake to avoid\n\nWriting the page as a tutorial. \"First, we import pandas. Then we load the data.\" The reviewer is not learning your project; they are making a decision about you, and every sentence that teaches them Python is a sentence not spent on evidence.\n\nWrite for a peer who could have built it themselves, and tell them the parts they would not have predicted.\n\n## The limitation\n\nThis only works if the project is real. Inventing a user count is checkable (a reviewer may ask which cooperative, or when the last commit was, or what the dispatchers complained about) and the conversation ends there. One small real project beats an impressive imaginary one, and it is much less exhausting to talk about."},"check":{"question":"Which of these belongs on a project page, near the top, even though beginners usually leave it out?","options":[{"text":"A short, specific account of what the project still gets wrong, and how you know.","correct":true},{"text":"A detailed architecture diagram of every component and how they connect.","correct":false,"tempting":"Feels like the professional thing to include, but a reviewer deciding about you in ninety seconds gets nothing from it that the first sentence did not give them."},{"text":"A step-by-step explanation of the code, so a reader can follow how it was built.","correct":false,"tempting":"Writes for a learner rather than an assessor, and spends the most valuable space on the page teaching rather than evidencing."},{"text":"A list of every technology and library used, to match the keywords in job adverts.","correct":false,"tempting":"Optimises for a keyword scan that a human reviewer is not performing, at the cost of the space where judgement would be shown."}]},"prev":{"slug":"the-data-you-can-legally-use","title":"Where portfolio data comes from, and what you may do with it","url":"https://addaly.com/learn/ai-careers/the-data-you-can-legally-use"},"next":{"slug":"how-hiring-really-works","title":"How people actually get in","url":"https://addaly.com/learn/ai-careers/how-hiring-really-works"},"authorship":"Founder and series editor: Dr Mustafa Mun. Written by AI models to a written standard. Exam keys checked blind by a second model: 3,665 of 3,666 agreed. Academic review invited.","review":{"status":"Draft, open for academic review"},"cite":"Addaly (2026) 'Writing up a project as a decision record', in Working in AI. Edited by M. Mun. Addaly. Available at: https://addaly.com/learn/ai-careers/the-case-study-page (Accessed: 13 October 2026).","licence":{"name":"CC BY-NC-SA 4.0","url":"https://creativecommons.org/licenses/by-nc-sa/4.0/"},"reader":{"schema":1,"title":"Writing up a project as a decision record","courseTitle":"Working in AI","module":{"index":3,"slug":"the-evidence","title":"The evidence: what gets tested, and how to prove you have it"},"answer":null,"keyIdea":"Write the project as a record of decisions (the mess, the choice, the number, and what it still gets wrong) because that is what a reviewer is reading for.","hero":{"kind":"figure","figure":{"t":"figure","label":"Figure","figure":{"type":"stack","title":"The page, in the order a reviewer reads it","layers":[{"label":"Title and first sentence: what it does, for whom, how often","detail":"read by everyone"},{"label":"Used by: a real count, with dates","detail":"the visible number"},{"label":"The mess, and exactly how you found it","detail":"the part a tutorial cannot fake"},{"label":"Two decisions, each with the alternative you rejected","detail":"judgement, not instructions"},{"label":"Does it work: thirty cases and a count","detail":"27 of 30, and what the misses share"},{"label":"What it gets wrong","detail":"raises credibility on everything above it"},{"label":"Run it: one command","detail":"a project that does not run is not evidence"}],"caption":"Ninety seconds: the title, the first sentence, whatever number is visible, then the section admitting what is wrong. They almost never read the code, which is why the mess and the number sit above it."},"alt":"Figure: The page, in the order a reviewer reads it. Layers, top to bottom: Title and first sentence: what it does, for whom, how often (read by everyone); Used by: a real count, with dates (the visible number); The mess, and exactly how you found it (the part a tutorial cannot fake); Two decisions, each with the alternative you rejected (judgement, not instructions); Does it work: thirty cases and a count (27 of 30, and what the misses share); What it gets wrong (raises credibility on everything above it); Run it: one command (a project that does not run is not evidence). Ninety seconds: the title, the first sentence, whatever number is visible, then the section admitting what is wrong. They almost never read the code, which is why the mess and the number sit above it."}},"blocks":[{"t":"h2","id":"the-ninety-second-reading-order","runs":[{"text":"The ninety-second reading order"}]},{"t":"p","runs":[{"text":"A reviewer opens your project page and reads in this order: the title, the first sentence, whatever number is visible, and then, if you have earned it, the section admitting what is wrong. They almost never read the code."}]},{"t":"p","runs":[{"text":"So write for that order. Everything that proves something goes above the fold, and the honest limitations go near the top rather than buried at the bottom, because their presence is itself the strongest signal on the page."}]},{"t":"h2","id":"the-template","runs":[{"text":"The template"}]},{"t":"code","lang":"","label":"Text","text":"# Bus delay tracker — Lagos, route 57\n\nTells a transport cooperative's dispatchers which departure\nwindow runs late most often. Updated nightly.\n\n**Used by** 6 dispatchers, weekly, since March 2026.\n\n## The mess\nThree of eleven months had GPS timestamps recorded in local\ntime and eight in UTC, with nothing labelling which. I found\nit because \"delays\" spiked by exactly one hour on the day the\ndevice firmware changed.\n\n## Two decisions\n- Dropped the first two weeks entirely rather than\n  interpolating. The device swap meant I could not tell\n  which clock any reading came from, and inventing a\n  correction would have hidden that.\n- Median rather than mean. Two breakdowns of four hours\n  each were dragging every weekly average upward.\n\n## Does it work\nI wrote 30 test journeys with known outcomes from the\ndispatchers' own paper log. It classifies 27 correctly.\nOf the 3 misses, all are journeys crossing midnight.\n\n## What it gets wrong\nNo handling of public holidays — a dispatcher found this\nbefore I did. Midnight-crossing journeys, as above.\n\n## Run it\n`make dev`, then open localhost:8000. Sample data included."},{"t":"p","runs":[{"text":"That page takes ninety minutes to write and outperforms three more projects."}]},{"t":"h2","id":"why-each-section-is-there","runs":[{"text":"Why each section is there"}]},{"t":"p","runs":[{"text":"The mess and how you found it.","b":true},{"text":" This is the only part of the page that cannot be faked by copying a tutorial. The detail that you noticed the spike was "},{"text":"exactly","i":true},{"text":" one hour is worth more than any architecture description, because it shows how you think when something is wrong."}]},{"t":"p","runs":[{"text":"Two decisions, with the rejected alternative.","b":true},{"text":" A decision with no discarded option is not a decision. Naming what you did not do is what distinguishes judgement from following instructions."}]},{"t":"p","runs":[{"text":"A number.","b":true},{"text":" From the previous lesson. Thirty test cases and a count. Most beginner portfolios contain no number at all, and the ones that do stand out immediately."}]},{"t":"p","runs":[{"text":"What it gets wrong.","b":true},{"text":" Counter-intuitive and true: admitting a limitation raises your credibility on everything else on the page, because it tells the reader you know how to look for problems. A page with no limitations reads as a page written by someone who has not checked."}]},{"t":"h2","id":"publishing-work-you-did-for-someone-else","runs":[{"text":"Publishing work you did for someone else"}]},{"t":"p","runs":[{"text":"If the project was for a client or an employer, you cannot simply publish it."}]},{"t":"ul","items":[[{"text":"Ask, in writing, before you publish anything.","b":true},{"text":" An email saying “may I write publicly about the approach, with your name and figures removed?” is usually answered yes, and it protects you."}],[{"text":"Never publish their data.","b":true},{"text":" Not a sample, not an anonymised extract, not “just the schema” if the schema is distinctive."}],[{"text":"Replace real figures with realistic invented ones and say so.","b":true},{"text":" “Figures changed for confidentiality; proportions preserved” is honest and reviewers accept it."}],[{"text":"A blurred screenshot is not anonymisation.","b":true},{"text":" The underlying CSV may still be in your repository, and blur can sometimes be reversed. Regenerate the screenshot with fake data instead."}],[{"text":"If you cannot publish it at all","b":true},{"text":", write a page about the "},{"text":"problem shape","i":true},{"text":" with no client details. “How I found a timezone bug in a delivery dataset” needs no client name."}]]},{"t":"h2","id":"show-it-moving","runs":[{"text":"Show it moving"}]},{"t":"p","runs":[{"text":"A forty-second screen recording of the thing working outperforms three paragraphs, because it proves the project exists in a way a repository does not. Free tools do this: "},{"text":"OBS Studio","b":true},{"text":" on any platform, the built-in recorder on macOS and Windows, "},{"text":"Peek","b":true},{"text":" on Linux. Loom is the paid product people reach for; nothing about a forty-second clip needs it."}]},{"t":"p","runs":[{"text":"Keep it short and unnarrated. Nobody watches minute two."}]},{"t":"h2","id":"the-mistake-to-avoid","runs":[{"text":"The mistake to avoid"}]},{"t":"p","runs":[{"text":"Writing the page as a tutorial. “First, we import pandas. Then we load the data.” The reviewer is not learning your project; they are making a decision about you, and every sentence that teaches them Python is a sentence not spent on evidence."}]},{"t":"p","runs":[{"text":"Write for a peer who could have built it themselves, and tell them the parts they would not have predicted."}]},{"t":"h2","id":"the-limitation","runs":[{"text":"The limitation"}],"role":"limit"},{"t":"p","runs":[{"text":"This only works if the project is real. Inventing a user count is checkable (a reviewer may ask which cooperative, or when the last commit was, or what the dispatchers complained about) and the conversation ends there. One small real project beats an impressive imaginary one, and it is much less exhausting to talk about."}]}],"check":{"question":[{"text":"Which of these belongs on a project page, near the top, even though beginners usually leave it out?"}],"options":[{"text":[{"text":"A short, specific account of what the project still gets wrong, and how you know."}],"correct":true,"tempting":null},{"text":[{"text":"A detailed architecture diagram of every component and how they connect."}],"correct":false,"tempting":[{"text":"Feels like the professional thing to include, but a reviewer deciding about you in ninety seconds gets nothing from it that the first sentence did not give them."}]},{"text":[{"text":"A step-by-step explanation of the code, so a reader can follow how it was built."}],"correct":false,"tempting":[{"text":"Writes for a learner rather than an assessor, and spends the most valuable space on the page teaching rather than evidencing."}]},{"text":[{"text":"A list of every technology and library used, to match the keywords in job adverts."}],"correct":false,"tempting":[{"text":"Optimises for a keyword scan that a human reviewer is not performing, at the cost of the space where judgement would be shown."}]}],"order":[1,2,0,3],"why":null},"prev":{"slug":"the-data-you-can-legally-use","title":"Where portfolio data comes from, and what you may do with it","minutes":9},"next":{"slug":"how-hiring-really-works","title":"How people actually get in","minutes":8}}}