Document Your School Software
Write a professional README and CONTRIBUTING guide for your project.
Introduction
30 Second Summary
You can build the most useful software in the world, but if someone visits your project page and can't figure out what it does in 10 seconds, they'll leave. Your documentation is the first impression.
In this project, you will rewrite the documentation for your Local Transcript Generator from scratch. You'll create a professional README with a compelling origin story, technology badges, a screenshot, and a contributor guide that makes your project look polished on GitHub.
What You'll Build
You will hand-write a complete documentation set in Markdown for your existing school transcript software project.
By the end of this project, you'll have:
- A professional README.md written by hand that tells the human story behind your software and makes visitors want to try it.
- A visual README with a screenshot, technology badges from Shields.io, and clear structure that renders beautifully on GitHub.
- A separate CONTRIBUTING.md guide that shows others how to set up and contribute to your project.
- Secret Mission: Write an Architecture Decision Record (ADR) explaining why you chose localStorage over a traditional backend.
Are there any prerequisites?
You need an existing public GitHub repository with a software project. This project uses the Local Transcript Generator as the example, but the documentation skills you learn apply to any project.
You should also have VS Code installed and a GitHub account ready to go. Git command line basics are guided step by step throughout the project.
Set Up Your Documentation Workspace
Good documentation is what separates a school project from a professional one. Right now, your Local Transcript Generator has an AI-generated README that does not tell the real story behind your software.
In this step, you will set up a fresh workspace for writing documentation by hand. You will create a dedicated Git branch, learn the Markdown preview workflow, and practice the five core syntax elements you will use throughout this project.
In this step, get ready to:
- Create a documentation branch and clear your existing README.
- Open the Markdown live preview in VS Code.
- Test the 5 core Markdown syntax elements.
Open your project and create a documentation branch
Working on a separate branch keeps your existing README safe on main until you are ready to merge. This is how professionals manage documentation changes alongside code.
- In VS Code, open the integrated terminal by pressing Ctrl+` (macOS and Windows).
- Make sure you are inside your Local Transcript Generator project folder. If not, navigate to it with cd followed by the path to your project.
- Create and switch to a new branch by running this command:
git checkout -b docs/rewrite-readmeWhat does this command do?
The -b flag tells git checkout to create a new branch AND switch to it in one step. The branch name docs/rewrite-readme uses a common naming convention where the prefix describes the type of work.
- You should see a message in your terminal confirming you switched to the new branch.
Seeing an error about not being a git repository?
Make sure your terminal is inside the project folder that you cloned from GitHub. Run ls to check what files are in the current directory. You should see your project files listed.
help me figure out why git checkout is not working in my terminal
Now clear out your existing README so you can start fresh.
- Open README.md in the VS Code editor by clicking on it in the Explorer sidebar.
- Select all the content with Cmd+A (macOS) or Ctrl+A (Windows).
- Delete it. The file should now be completely empty.
- Save the file with Cmd+S (macOS) or Ctrl+S (Windows).
Open the Markdown preview
VS Code has a built-in Markdown preview that updates in real-time as you type. This lets you see exactly how your documentation will look on GitHub without leaving the editor.
- With README.md open in the editor, press Cmd+K V (macOS) or Ctrl+K V (Windows) to open a side-by-side Markdown preview.
How does this shortcut work?
This is a two-key chord. Press and hold Cmd (or Ctrl) then tap K. Release both keys, then press V by itself. A preview pane opens to the right of your editor.
- You should see an empty preview pane appear on the right side of your editor. As you type Markdown in the left pane, the preview updates instantly on the right.
Preview pane not appearing?
Make sure README.md is the active file in your editor (click on its tab). The preview only works when a Markdown file is focused.
help me open the Markdown preview in VS Code
Test the core Markdown syntax
Before writing your real documentation, try each of the five core Markdown elements to see how they render. This quick test confirms your preview is working and builds your muscle memory.
- Type the following test content into your empty README.md:
# My Heading
This is **bold** text.
- First item
- Second item
```
some code here
```
[Click me](https://example.com)What are these five elements?
- # My Heading creates a heading. The number of # symbols sets the heading level (1 through 6).
- **bold** wraps text in double asterisks to make it bold.
- - item creates a bullet list. Each line starting with a dash becomes a list item.
- Triple backticks open and close a code block for displaying commands or code snippets.
- [text](url) creates a clickable link. The text in brackets is what people see. The URL in parentheses is where the link goes.
- Check the preview pane on the right. You should see a large heading, bold text, a bulleted list, a grey code block, and a blue clickable link.
- Once you have confirmed all five elements render correctly, select all the text and delete it again.
- Save README.md. The file should be completely empty and ready for your real documentation.
Something not rendering correctly?
Make sure you have a blank line between each element. Markdown uses blank lines to separate blocks. If your heading and list run together, add a blank line between them.
help me figure out why my Markdown is not rendering in the preview
✔️ Awesome, I've got everything!
Great. Make sure you have saved README.md as an empty file. You are ready to start writing your real documentation.
ⓧ I'd like to double check the full code
Your README.md should be completely empty at this point. There is no content in the file. If you see any leftover text from your test, select all and delete it, then save.
Your workspace is set up with a fresh branch and an empty README ready to fill. Next, you will write the project header and tell the story of why your software exists.
Write the Project Header and Story
Your workspace is ready and you know the core Markdown syntax. Now it is time to write the content that will make your project stand out.
A great README tells a story. It opens with a clear title and description, shows off the tech stack with visual badges, and explains the real problem behind the code. In this step, you will write the project header and the origin story that makes your documentation human.
In this step, get ready to:
- Write a project title and one-line description.
- Add technology badges using Shields.io.
- Write the origin story and embed a screenshot.
Write the project title and badges
The top of your README is the first thing visitors see. A clear title, a one-sentence description, and a row of technology badges immediately communicate what the project is and what it is built with.
What are Shields.io badges?
Shields.io generates small, colourful labels that display a technology name and optional version. You build the badge by constructing a URL with the label, message, colour, and logo parameters.
Static badges do not require any API keys or authentication. They use a simple URL pattern you can write by hand.
- Add the following to your empty README.md file:
# Local Transcript Generator
A local web app for automating student transcript creation, previewing, and printing for schools.
What does this code do?
The first line (# Local Transcript Generator) creates a level-1 heading. The sentence below it serves as the project tagline.
Each badge line uses the Markdown image syntax  but points to a Shields.io URL instead of a local file. The URL encodes the label, version, colour, and logo in its path and query parameters.
- Save README.md.
- Check the Markdown preview pane. You should see a large heading, a plain-text description, and three coloured badges with technology logos.
Badges not showing in the preview?
VS Code's built-in Markdown preview does not always load remote images. If you see the alt text (e.g. "Next.js") instead of a coloured badge, the syntax is correct. The badges will render properly on GitHub once you push.
If you see raw text like  with no rendering at all, make sure there is no extra space between the ! and the [.
Why aren't my Shields.io badges rendering in VS Code preview?
Write the "Why This Exists" section
Generic READMEs list features. Great READMEs tell the story of the problem that made the project necessary. This section is what separates your documentation from anything an AI could generate.
- Add the following below your badges row in README.md (leave a blank line between the last badge and this section):
## Why This Exists
I built this after watching my teacher struggle to print my transcript correctly. The school staff were using different Microsoft Word templates for each grade level (G9-G12, G10-G12, etc.), manually copying student data between files. Mistakes were common and the process was painfully slow.
This app replaces that workflow with a single tool that handles all grade templates, stores student records locally, and exports print-ready transcripts in one click.Why does personal storytelling matter here?
Hiring managers and collaborators read hundreds of READMEs. Most are dry feature lists. A brief, honest story about why you built something signals that you identify real problems and solve them with code.
The first paragraph names the problem you witnessed. The second paragraph names your solution. That two-paragraph pattern is easy for readers to scan.
- Save README.md.
- Check the preview pane. You should see a bold "Why This Exists" heading followed by two paragraphs telling the transcript story.
Heading not rendering as a heading?
Make sure there is a blank line before ## Why This Exists. Markdown requires a blank line before headings to render them correctly.
Also confirm there is a space between the ## and the heading text. Without the space, Markdown treats the line as plain text.
Why isn't my Markdown heading rendering properly?
Add your screenshot
A screenshot gives visitors an instant understanding of what the app looks like. You will store the image inside the repository and reference it with a relative path so it works for anyone who clones the project.
- Create the image folder by running this command in your integrated terminal:
mkdir -p docs/images- Confirm the folder exists by running:
ls docsYou should see images listed in the output.
Getting a "cannot create directory" error on Windows?
If your terminal is PowerShell and does not recognise the -p flag, run mkdir docs\images instead. PowerShell's mkdir creates parent directories automatically without a flag.
Help me create the docs/images folder on Windows.
Now you need a screenshot of your running app to embed in the README.
- Take a screenshot of your Local Transcript Generator showing the transcript preview or print layout.
- Save or move the screenshot into the docs/images/ folder.
- Name the file transcript-preview.png.
Use a descriptive file name
Naming your image transcript-preview.png instead of something like screenshot1.png makes the repository easier to navigate for future contributors.
- Add the following line at the bottom of your README.md (below the "Why This Exists" paragraphs, with a blank line above it):
What does this line do?
This uses the same Markdown image syntax as the badges, but points to a local file instead of a remote URL. The path docs/images/transcript-preview.png is relative to the README file. GitHub resolves relative paths automatically, so anyone viewing the repo sees the image.
- Save README.md.
- Check the Markdown preview pane. You should see your screenshot displayed below the "Why This Exists" text.
Image not showing in the preview?
Make sure the file is actually saved as transcript-preview.png inside docs/images/. The path in your Markdown must match the folder structure exactly, including case.
If you saved the file as .jpg or .jpeg, update the extension in the Markdown line to match your actual file name.
Why isn't my image showing in the Markdown preview?
✔️ Awesome, I've got everything!
Great. Double check you have saved your file and that the preview shows the title, badges, story, and screenshot.
ⓧ I'd like to double check the full code
Here is the complete README.md as it should look at the end of this step:
# Local Transcript Generator
A local web app for automating student transcript creation, previewing, and printing for schools.
## Why This Exists
I built this after watching my teacher struggle to print my transcript correctly. The school staff were using different Microsoft Word templates for each grade level (G9-G12, G10-G12, etc.), manually copying student data between files. Mistakes were common and the process was painfully slow.
This app replaces that workflow with a single tool that handles all grade templates, stores student records locally, and exports print-ready transcripts in one click.
Your README already has a professional header and a compelling story. Next up, you will add the technical documentation sections that help others actually use and understand your project.
Write the Technical Documentation Sections
Your README already has a compelling origin story and a screenshot that shows what the app looks like. Visitors know why this project exists. Now they need to know how to actually use it.
In this step, you will write the three sections that turn your README from a story into a usable reference. Someone discovering your repo should be able to understand the features, clone it, run it, and grasp the user flow without reading your code.
In this step, get ready to:
- Write a Features section that describes user benefits, not just technical facts.
- Write a Getting Started section with copy-paste setup commands.
- Write a How It Works section explaining the user flow.
Write the Features section
A Features section should describe what the user gains from using your software. Instead of just listing technical components, frame each bullet as a benefit someone would care about.
- In README.md, place your cursor on the line below the screenshot image, then add the following Features section:
## Features
- Grade-specific templates (G9-G12, G10-G12, G11-G12, G12) that automatically adapt the input form
- Student records saved locally in the browser with no backend or internet required
- Print-ready transcript preview that matches the school's official format
- One-click export to Word document (.docx) for printing or sharing
- JSON export and import for backing up or transferring student data between machines
- Search and filter to quickly find students across saved recordsWhat makes these bullets effective?
Each bullet describes a user-facing benefit, not just a technical fact. "Grade-specific templates that automatically adapt the input form" tells the reader what happens for them. Compare that to a weak alternative like "template selection" which says nothing useful.
Notice the pattern: feature name + what it does for the user. This is the format professional open-source projects use.
- Save README.md.
- Check your Markdown preview pane. You should see a bold "Features" heading followed by six bullet points rendered as a clean list.
Bullets not rendering as a list?
Make sure there is a blank line between the ## Features heading and the first bullet. Markdown needs that blank line to recognise the heading as separate from the list.
Also confirm each bullet starts with a dash followed by a space (- ). Missing the space will break the list formatting.
Help me fix my Markdown bullet list formatting
Write the Getting Started section
The Getting Started section is the most practical part of your README. Someone who wants to try your app should be able to copy-paste the commands and have it running in under a minute.
- Below the Features section in README.md, add the following Getting Started section:
## Getting Started
### Prerequisites
- Node.js (version 18 or higher)
### Installation
```bash
git clone https://github.com/YOUR-USERNAME/local-transcript-generator.git
cd local-transcript-generator
npm install
npm run dev
```
Open the app at [http://localhost:3000](http://localhost:3000).
### Production Build
```bash
npm run build
npm start
```What does this section do?
The triple backticks with bash after them create a fenced code block with syntax highlighting. On GitHub, this renders as a grey box with a copy button, making it easy for visitors to grab the commands.
The YOUR-USERNAME placeholder tells future users to substitute their own GitHub username when forking. This is a common convention in open-source READMEs.
The Production Build sub-section gives users who want to deploy the app (not just develop it) the commands they need.
- Save README.md.
- In the preview pane, confirm you see three sub-headings (Prerequisites, Installation, Production Build) and that the terminal commands appear inside grey code blocks.
Code block not rendering?
Fenced code blocks need exactly three backticks on their own line to open and three backticks on their own line to close. If you see raw backtick characters in the preview, check that you have not accidentally added a space before the opening backticks or missed the closing set.
Also make sure the word bash sits directly after the opening backticks with no space (like ```bash).
Help me fix my Markdown fenced code block
Write the How It Works section
The How It Works section gives visitors a mental model of the app without them needing to read any source code. Numbered steps work well here because the user flow is sequential.
- Below the Getting Started section in README.md, add the following How It Works section:
## How It Works
1. Create a new student record with their name, gender, age, and grade template
2. Switch to the Grades tab and enter academic scores by subject and semester
3. Use the Preview tab to see the formatted transcript exactly as it will print
4. Export as a Word document or print directly from the browser
5. Use Data Management to export all records as JSON (for backup) or import from another machine
All data is stored in your browser's localStorage. Nothing is sent to any server.Why mention localStorage here?
The closing line about localStorage answers a question visitors will immediately have: "Where does the data go?" By stating it upfront, you prevent confusion and reassure users that student data stays private on their machine.
- Save README.md.
- In the preview pane, confirm you see a numbered list (1 through 5) under the "How It Works" heading, followed by the localStorage note as a standalone paragraph.
Numbered list showing as plain text?
Markdown ordered lists need a number, a period, and a space before each item (like 1. ). If you are missing the space after the period, the list will not render.
Also check that there is a blank line between the heading and the first list item.
Help me fix my Markdown numbered list
✔️ Awesome, I've got everything!
Great. Double check you have saved README.md and that all three new sections (Features, Getting Started, How It Works) are visible in your preview.
ⓧ I'd like to double check the full code
Here is the complete README.md as it should look at this point. Compare it with what you have:
# Local Transcript Generator
A local web app for automating student transcript creation, previewing, and printing for schools.
## Why This Exists
I built this after watching my teacher struggle to print my transcript correctly. The school staff were using different Microsoft Word templates for each grade level (G9-G12, G10-G12, etc.), manually copying student data between files. Mistakes were common and the process was painfully slow.
This app replaces that workflow with a single tool that handles all grade templates, stores student records locally, and exports print-ready transcripts in one click.
## Features
- Grade-specific templates (G9-G12, G10-G12, G11-G12, G12) that automatically adapt the input form
- Student records saved locally in the browser with no backend or internet required
- Print-ready transcript preview that matches the school's official format
- One-click export to Word document (.docx) for printing or sharing
- JSON export and import for backing up or transferring student data between machines
- Search and filter to quickly find students across saved records
## Getting Started
### Prerequisites
- Node.js (version 18 or higher)
### Installation
```bash
git clone https://github.com/YOUR-USERNAME/local-transcript-generator.git
cd local-transcript-generator
npm install
npm run dev
```
Open the app at [http://localhost:3000](http://localhost:3000).
### Production Build
```bash
npm run build
npm start
```
## How It Works
1. Create a new student record with their name, gender, age, and grade template
2. Switch to the Grades tab and enter academic scores by subject and semester
3. Use the Preview tab to see the formatted transcript exactly as it will print
4. Export as a Word document or print directly from the browser
5. Use Data Management to export all records as JSON (for backup) or import from another machine
All data is stored in your browser's localStorage. Nothing is sent to any server.Your README now covers the full picture: why the project exists, what it looks like, what it does, how to run it, and how it works. Next up, you will create a CONTRIBUTING.md file for collaborators and push everything to GitHub.
Create the CONTRIBUTING.md and Push to GitHub
Your README now has everything a visitor needs to understand and run your project. The next step is making it easy for other people to contribute code back.
A separate CONTRIBUTING.md file is the standard way open-source projects communicate contribution guidelines. You will create one, add a License section to your README, then push everything to GitHub so the world can see it.
In this step, get ready to:
- Create a CONTRIBUTING.md with setup and contribution instructions.
- Add a License section to your README that links to the new guide.
- Commit and push your documentation branch to GitHub.
Create a CONTRIBUTING.md file
A contributor guide answers the question: "I want to help. How do I get started?" You will write one that covers development setup, project structure, and the pull request workflow.
- In the Explorer sidebar in VS Code, right-click the project root folder.
- Select New File.
- Name the file CONTRIBUTING.md.
- Open the Markdown preview alongside the file by pressing Ctrl+K V (Windows) or Cmd+K V (macOS).
- Write the file header and Development Setup section by pasting the following into CONTRIBUTING.md:
# Contributing to Local Transcript Generator
Thank you for your interest in contributing! This guide will help you get set up and start making changes.
## Development Setup
### Prerequisites
- Node.js (version 18 or higher)
- Git
### Getting Started
1. Fork this repository on GitHub
2. Clone your fork locally:
```bash
git clone https://github.com/YOUR-USERNAME/local-transcript-generator.git
cd local-transcript-generator
```
3. Install dependencies:
```bash
npm install
```
4. Start the development server:
```bash
npm run dev
```
5. Open [http://localhost:3000](http://localhost:3000) to see the appWhat does this section do?
The Development Setup section tells a contributor exactly what they need installed and the exact sequence of commands to get your project running on their machine.
Nesting bash code blocks inside numbered steps means a contributor can follow along command-by-command without guessing.
- Check the Markdown preview. You should see a title, a bulleted prerequisites list, and a numbered Getting Started list with grey code blocks inside it.
Code blocks not rendering inside the list?
The triple backticks for each code block must be indented with exactly 3 spaces to sit inside the numbered list item. If they are flush-left, Markdown treats them as a new top-level block and breaks the list.
Help me fix indentation in my CONTRIBUTING.md code blocks
- Add the Project Structure section below the Development Setup content by pasting this next:
## Project Structure
- `app/page.tsx` - Main app shell with tabs, filters, and student state management
- `components/student-form.tsx` - Student details form and validation
- `components/grades-input.tsx` - Grade matrix and summary calculations
- `components/print-preview.tsx` - Transcript preview and print workflow
- `components/word-export.tsx` - Export transcript to Word file
- `components/data-manager.tsx` - JSON import/export and data clearing
- `lib/file-manager.ts` - Browser storage utilities for saving and loading records
- `components/ui/*` - Shared UI primitives (buttons, inputs, tables, cards)Why list project structure?
A contributor landing in your repo for the first time has no idea which files do what. This section acts as a map so they can jump straight to the file that handles the feature they want to change.
- Check the preview. You should see a bulleted list where each file path renders in monospace font with a short description beside it.
- Add the How to Contribute and Notes sections by pasting this at the end of the file:
## How to Contribute
1. Create a new branch for your feature or fix:
```bash
git checkout -b feature/your-feature-name
```
2. Make your changes and test them locally
3. Commit with a clear message:
```bash
git commit -m "feat: describe what you changed"
```
4. Push to your fork:
```bash
git push origin feature/your-feature-name
```
5. Open a Pull Request on GitHub describing your changes
## Notes
- Student names are validated to include first, middle, and last names
- Grade templates adjust the available grade years automatically
- The app stores data in localStorage only. No external API calls are madeWhat does this section do?
The How to Contribute section walks a first-time contributor through the standard Git branching workflow: create a branch, make changes, commit, push, and open a pull request.
The Notes section captures project-specific rules (like name validation) so contributors do not accidentally break existing behavior.
- Save CONTRIBUTING.md.
- Check the preview one more time. You should see all four sections (Development Setup, Project Structure, How to Contribute, Notes) rendering with proper headings, lists, and code blocks.
Seeing raw backticks instead of code blocks?
Make sure each opening and closing set of triple backticks is on its own line. A stray space after the closing backticks can prevent Markdown from recognizing the block.
Help me debug why my Markdown code blocks are showing as raw text
✔️ Awesome, I've got everything!
Great. Double check you have saved CONTRIBUTING.md before moving on.
ⓧ I'd like to double check the full code
# Contributing to Local Transcript Generator
Thank you for your interest in contributing! This guide will help you get set up and start making changes.
## Development Setup
### Prerequisites
- Node.js (version 18 or higher)
- Git
### Getting Started
1. Fork this repository on GitHub
2. Clone your fork locally:
```bash
git clone https://github.com/YOUR-USERNAME/local-transcript-generator.git
cd local-transcript-generator
```
3. Install dependencies:
```bash
npm install
```
4. Start the development server:
```bash
npm run dev
```
5. Open [http://localhost:3000](http://localhost:3000) to see the app
## Project Structure
- `app/page.tsx` - Main app shell with tabs, filters, and student state management
- `components/student-form.tsx` - Student details form and validation
- `components/grades-input.tsx` - Grade matrix and summary calculations
- `components/print-preview.tsx` - Transcript preview and print workflow
- `components/word-export.tsx` - Export transcript to Word file
- `components/data-manager.tsx` - JSON import/export and data clearing
- `lib/file-manager.ts` - Browser storage utilities for saving and loading records
- `components/ui/*` - Shared UI primitives (buttons, inputs, tables, cards)
## How to Contribute
1. Create a new branch for your feature or fix:
```bash
git checkout -b feature/your-feature-name
```
2. Make your changes and test them locally
3. Commit with a clear message:
```bash
git commit -m "feat: describe what you changed"
```
4. Push to your fork:
```bash
git push origin feature/your-feature-name
```
5. Open a Pull Request on GitHub describing your changes
## Notes
- Student names are validated to include first, middle, and last names
- Grade templates adjust the available grade years automatically
- The app stores data in localStorage only. No external API calls are madeAdd a License section to your README
A License section tells visitors whether they can reuse your code. You will also link to your new CONTRIBUTING.md so people can find it from the main page.
- Switch to README.md in the editor.
- Scroll to the very bottom of the file, after the "How It Works" section.
- Add the following License section at the end:
## License
This project is not currently licensed for reuse.
See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and contribution guidelines.What does this section do?
The License heading makes your reuse policy explicit instead of leaving visitors guessing. The link to CONTRIBUTING.md uses a relative path, which means it works both on GitHub and in any local clone of the repo.
- Save README.md.
- Check the Markdown preview. You should see a "License" heading at the bottom with the text and a clickable link to CONTRIBUTING.md.
Link showing as plain text?
Make sure there is no space between the square brackets and the parentheses in [CONTRIBUTING.md](CONTRIBUTING.md). Even one space breaks the link syntax.
Help me fix my Markdown link syntax
✔️ Awesome, I've got everything!
Great. Double check you have saved README.md before moving on.
ⓧ I'd like to double check the full code
# Local Transcript Generator
A local web app for automating student transcript creation, previewing, and printing for schools.
## Why This Exists
I built this after watching my teacher struggle to print my transcript correctly. The school staff were using different Microsoft Word templates for each grade level (G9-G12, G10-G12, etc.), manually copying student data between files. Mistakes were common and the process was painfully slow.
This app replaces that workflow with a single tool that handles all grade templates, stores student records locally, and exports print-ready transcripts in one click.
## Features
- Grade-specific templates (G9-G12, G10-G12, G11-G12, G12) that automatically adapt the input form
- Student records saved locally in the browser with no backend or internet required
- Print-ready transcript preview that matches the school's official format
- One-click export to Word document (.docx) for printing or sharing
- JSON export and import for backing up or transferring student data between machines
- Search and filter to quickly find students across saved records
## Getting Started
### Prerequisites
- Node.js (version 18 or higher)
### Installation
```bash
git clone https://github.com/YOUR-USERNAME/local-transcript-generator.git
cd local-transcript-generator
npm install
npm run dev
```
Open the app at [http://localhost:3000](http://localhost:3000).
### Production Build
```bash
npm run build
npm start
```
## How It Works
1. Create a new student record with their name, gender, age, and grade template
2. Switch to the Grades tab and enter academic scores by subject and semester
3. Use the Preview tab to see the formatted transcript exactly as it will print
4. Export as a Word document or print directly from the browser
5. Use Data Management to export all records as JSON (for backup) or import from another machine
All data is stored in your browser's localStorage. Nothing is sent to any server.
## License
This project is not currently licensed for reuse.
See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and contribution guidelines.Commit and push to GitHub
Both files are ready. Now you will commit your changes and push the branch so your documentation goes live on GitHub.
- Stage all your new and changed files by running this command in the integrated terminal:
git add .- Commit with a descriptive message by running:
git commit -m "docs: rewrite README and add CONTRIBUTING guide"Why this commit message format?
The docs: prefix is a conventional commit style that labels the type of change. It makes your Git history scannable at a glance. Other common prefixes include feat: for features and fix: for bug fixes.
- Push the branch to GitHub by running:
git push -u origin docs/rewrite-readmeWhat does -u do?
The -u flag sets origin docs/rewrite-readme as the upstream tracking branch. After this first push, you can use just git push without the extra arguments.
- Visit your repository on GitHub in your browser.
- Switch to the docs/rewrite-readme branch using the branch dropdown near the top-left of the page.
- You should see your new README rendered with badges, your screenshot, the origin story, and all technical sections displaying correctly.
- Click CONTRIBUTING.md in the file list to confirm it renders properly too.
Push rejected or permission denied?
Make sure you are pushing to a repository you own (not someone else's). If you see a permission error, check that your GitHub credentials are configured in Git.
If the push says the branch already exists, you may have pushed previously. Run git push without the -u flag instead.
Help me fix a git push error
Secret mission
Write an Architecture Decision Record
Your documentation explains what your project does and how to use it. But what about why you made the choices you did? In this secret mission, you will write an Architecture Decision Record (ADR) that captures the reasoning behind choosing localStorage over a backend database.
Clean Up Your Resources
Clean Up Your Resources
This project runs entirely locally and all documentation lives in your existing GitHub repository. There are no ongoing costs or paid resources to worry about.
Decide whether to merge your documentation branch into main, leave it for later, or remove it entirely.
Resources you used:
- Git branch docs/rewrite-readme (local and on GitHub).
- Documentation files: README.md, CONTRIBUTING.md, docs/adr/001-local-storage-over-backend.md, docs/images/transcript-preview.png.
Keep everything running
No action needed. Choose this if you are ready to make your new documentation live.
- Merge your branch into main to publish the documentation. Switch to main and merge by running:
git checkout main
git merge docs/rewrite-readme
git push- Your repository on GitHub will now show the new README, CONTRIBUTING guide, and ADR on the main branch.
Pause - I'll come back to this later
Leave the branch as-is on GitHub. Your work is safely stored and you can come back to merge it anytime.
- No action required. Your docs/rewrite-readme branch is already pushed to GitHub and will persist until you decide to merge or delete it.
- When you are ready to continue, open the project in VS Code and run git checkout docs/rewrite-readme to pick up where you left off.
Delete - I don't want to use this again
Remove the documentation branch and all changes if you want to start fresh or discard this work.
- Switch back to your main branch by running:
git checkout main- Delete the local branch by running:
git branch -D docs/rewrite-readme- Delete the remote branch on GitHub by running:
git push origin --delete docs/rewrite-readme- This removes the branch from both your machine and GitHub. Your main branch remains untouched.
Nice Work!
Nice Work!
You just wrote professional documentation for a real software project, entirely by hand. Your Local Transcript Generator now tells the story of why it exists and makes it easy for anyone to get started.
Here's what you learned:
- Written Markdown by hand, using headings, bold, lists, code blocks, links, and images to build a complete README from scratch.
- Created a professional README.md with Shields.io badges, a screenshot, and a compelling origin story that makes your project stand out.
- Written a CONTRIBUTING.md guide and used Git branching to manage documentation changes separately from code.
- Secret Mission: wrote an Architecture Decision Record documenting why you chose localStorage over a backend database.
Ready to quiz yourself?