Document your work

Outcome

You will add a README.md file to a tested website project. A new reader will be able to understand the result, open it, find important files, review your decisions and test evidence, and identify reused work.

Why this matters

The website shows what the product does. Documentation explains how another person can work with it. Accurate documentation makes a project easier to review, maintain, hand over, and return to after time away.

What you will practice

Write documentation for a named reader and purpose.
Describe a project result without making claims that the evidence does not support.
Give complete setup and run instructions with expected results.
Explain project structure and selected technical decisions.
Record verification, known limits, credits, and license information.
Test documentation from a fresh-reader position and revise unclear instructions.

What is new and what is reused

New: Project documentation, README, audience, evidence-based claim, prerequisite, known limitation, credit, and license note.
Reused: Project folders, relative paths, Markdown, semantic structure, images, validation, manual tests, issue records, and technical decisions.

Starting point

Before you start

Your completed quality-profile project and private repository from the validation and testing lesson.
A completed test-report.md with the final status of each required check.
The source page or license information for each image, icon, font, code sample, or other asset that you did not create.
VS Code and a current browser.

Current state: The website and test report contain useful information, but a new reader must inspect the project and guess how to open it, how it is organized, what was verified, and which work came from another source.
First action: Open quality-profile in VS Code, create README.md at the project root, and add the project title plus a one-sentence purpose.
First checkpoint: README.md names the product, describes its result, and states who the page is for without requiring the reader to inspect the source first.
Help trigger: Use the recovery note or ask for help if you cannot verify a claim, do not know the source or license of an asset, or cannot reproduce your own run instructions from a closed browser.

Required result

You have completed the lesson when quality-profile/README.md includes:

a specific project title, purpose, intended reader, and current result;
the prerequisites and exact steps needed to open the website;
an expected result after the run steps;
a short file tree with the role of each important file and folder;
two or more technical decisions with reasons tied to the product;
a verification summary based on test-report.md;
honest known limitations and work outside the current scope;
credits and license notes for reused assets, or an explicit statement that all assets are your own;
no private data, secret value, local account name, school-system link, or unsupported quality claim; and
evidence that another person, or you in a fresh-reader test, followed the instructions and reached the expected result; and
a clean local working tree with the documentation commit pushed to the private quality-profile repository.

Documentation map

A useful README connects a reader to the project and its evidence

Documentation does not replace the product or its tests. It gives another person an accurate route through both.

Write for a named reader

Documentation becomes more useful when you decide who needs it and what that person must do.

For this project, use this primary reader:

A developer or teacher who has the project folder but has not seen the website before.

The reader needs to answer three questions:

What is this product and what result should I see?
How do I open, inspect, and test it?
Which claims, limits, and reused resources should I know about?

Inventory evidence before you write

Do not reconstruct the project from memory. Inspect the current files and test report.

Open the project root in VS Code.
List the important files and folders. Ignore editor settings, operating-system files, and temporary files unless the reader needs them.
Open test-report.md. Mark which tests passed, which limitation remains, and which tools or browser conditions you used.
Find the source and license information for each item that you did not create.
Write uncertain information under a temporary Questions to resolve heading. Do not turn it into a factual claim until you verify it.

Your project can have this structure:

Directoryquality-profile/
- Directoryimages/
  - workspace-480.webp
  - workspace-960.webp
- index.html
- styles.css
- test-report.md
- README.md

Checkpoint: The source material is ready

What now works: You have a file inventory, verified test results, and source information for reused work. Uncertain details are questions, not claims.
Files changed: README.md, test-report.md
What remains: Turn the verified information into reader-focused sections and instructions.
Next action: Add the README structure and complete the Overview section.
If it does not work: If a source or license is missing, remove the affected asset from the documented result or pause that claim until you can verify the reuse terms.

Build the README structure

Add these headings to README.md:

# Project title

## Overview

## Open the website

## Project structure

## Technical decisions

## Verification

## Known limitations

## Credits and licenses

The headings create a stable reading route. Complete the sections in any order that supports your work.

Describe the product and current result

The overview must name the product, intended reader, and visible result. Prefer concrete statements.

# Profile website

## Overview

This project is a responsive profile page for a fictional junior web developer.
It helps a visitor review the developer's skills, selected work, and contact route.
The current version contains semantic HTML, reusable CSS, responsive images,
keyboard-visible navigation, and layouts for wide and narrow screens.

The example does not say that the page is fully accessible, perfect, professional, or production-ready. Those broad claims need more evidence than the lesson tests provide.

Check every quality claim

For each claim in the overview, ask:

Which file shows the implementation?
Which test case shows that it worked in a named condition?
Does the wording describe the tested result, or does it imply more?

Change an unsupported claim into a specific fact or move it to Known limitations.

Give reproducible open instructions

A useful procedure states the prerequisite, action, and expected result. Test the procedure from a closed browser.

## Open the website

### Prerequisites

- A current desktop browser
- The complete project folder, including the `images` folder

### Steps

1. Open the project folder.
2. Open `index.html` in a current browser.
3. Keep `index.html`, `styles.css`, and the `images` folder in their existing relative locations.

Expected result: The profile page loads with styled sections and visible images.
The navigation links move to the matching sections on the same page.

If your project needs a local server, name the tool and command, state where the command must run, and give the expected local URL. Do not add a server requirement to a static project that works correctly without one.

Checkpoint: A new reader can reach the product

What now works: The overview identifies the product and reader. The open procedure includes prerequisites, actions, and an observable expected result.
Files changed: README.md
What remains: Explain the project structure, decisions, verification, limits, and sources.
Next action: Document the important files and two decisions that shaped the result.
If it does not work: Close the browser and follow only the written instructions. Revise the first step where you need information that the README does not provide.

Explain structure without listing every file

Show the paths that help the reader inspect or change the product. Follow the file tree with one short role for each entry.

## Project structure

- `index.html` — page content and semantic structure
- `styles.css` — tokens, reusable components, layout, and responsive rules
- `images/` — local raster and SVG assets used by the page
- `test-report.md` — validation results, manual test evidence, repairs, and retests
- `README.md` — project overview, run instructions, decisions, limits, and credits

Do not paste the complete HTML or CSS into the README. Link a claim to the relevant file or selector instead.

Record decisions and reasons

A technical decision states what you selected, why it fits the product, and what effect it has. It is not a timeline of every edit.

## Technical decisions

### Semantic section structure

The page uses `header`, `nav`, `main`, `section`, and `footer` to identify
the role of each major region. The heading order follows the content hierarchy.

### Reusable card class

Project entries share one `.project-card` class. This keeps spacing, borders,
and heading treatment consistent while each card keeps its own content.

### Responsive source images

The profile image uses 480-pixel and 960-pixel WebP files in `srcset`.
The browser can select a suitable source for the rendered size and pixel density.

Choose decisions that shaped the product. Good candidates include semantic elements, class reuse, layout method, breakpoint behavior, image format, image alternatives, navigation, focus design, and content hierarchy.

Report verification without copying the test report

Summarize the scope and final result. Keep detailed steps and issue history in test-report.md.

## Verification

See `test-report.md` for conditions, expected results, actual results, and issue records.

The final test pass covered:

- HTML validation and VS Code CSS diagnostics
- page load and heading structure
- internal links and browser history
- local images and alternative text
- keyboard navigation and visible focus
- layout at about 320 CSS pixels
- layout at 200% browser zoom

Tests were run in Firefox 141 on Windows 11 on 8 August 2026.

Use your actual browser, operating system, date, and results. If a required test did not pass, do not place it in the passed list.

State limits and unfinished work

Known limitations make the current boundary visible. They are not apologies.

Examples include:

the project has been tested in one browser only;
a contact link uses a placeholder address;
the page has not had assistive-technology user testing;
the CMS export requires import into WordPress Playground before review; or
real network performance is outside the local test scope.

Do not hide a known failure inside vague wording such as “minor improvements remain.” Name the behavior, condition, and impact.

Credit reused work and record licenses

For each reused asset, record enough information for a reader to identify the source and reuse terms. Include:

the asset name or description;
its creator or publisher when known;
a direct source URL;
the license or stated permission; and
any changes you made, such as crop, resize, recolor, or compression.

## Credits and licenses

- `images/workspace-960.webp` — source photograph created for this project;
  cropped to 3:2 and compressed to WebP by the project author.
- Interface icons — [Lucide](https://lucide.dev/), ISC License;
  line color changed to match the page theme.

Replace the example with your real sources. A search result, image preview, or copied filename is not a license. Open the original source page and verify the terms.

Test the documentation as a reader

Run a fresh-reader test after the draft is complete.

Close the website and collapse the project folders in VS Code.
Start at the first line of README.md.
Follow the open procedure exactly. Do not use a remembered step that is absent from the document.
Compare the browser result with the overview and expected result.
Use the project structure to find the main content, styles, images, and test evidence.
Check two technical claims against the named files or selectors.
Open each credit link and confirm that the source and license information match the README.
Record the first point where you guessed, paused, or reached a different result.
Revise that point and repeat the affected route.

If another person is available, ask them to perform the same test without spoken guidance. Their questions are evidence about the documentation, not a measure of their skill.

Checkpoint: The documentation has reader evidence

What now works: A reader can open the website, locate important files, check selected claims, and identify reused work by following README.md.
Files changed: README.md
What remains: Run the final accuracy, privacy, link, and readability checks.
Next action: Complete the self-check and save the documented project as the input for the presentation lesson.
If it does not work: If the reader needs spoken information, add that information at the first relevant step and repeat only the affected part of the test.

Assistance

Assistance 1 — Choose the next README section

Complete one section at a time in this order: Overview, Open the website, Project structure, Technical decisions, Verification, Known limitations, then Credits and licenses. Stop after one complete section if you need a short work boundary.

Assistance 2 — Turn a broad claim into an evidence-based statement

Replace “The site is fully responsive and accessible” with the tested condition: “The required content remained available without horizontal page scroll at about 320 CSS pixels and 200% zoom, and all interactive elements were reachable with the keyboard in the tested browser.”

Assistance 3 — Diagnose incomplete run instructions

Close the browser, move to the project root, and follow the README one line at a time. Mark the first action that requires an unnamed tool, path, file, command, or expected result. Add that missing information near the action.

Assistance 4 — Use a focused README drafting frame

For each section, write one answer to one question: What is it? How do I open it? Where is each important part? Why did you choose this approach? What did you test? What remains outside the result? What did you reuse?

Assistance 5 — Review a complete example structureExample solution

A complete README can use the required heading structure from this lesson, the example overview, the open procedure, the five-entry project structure, two technical decisions, a verification summary linked to test-report.md, at least one specific limitation, and verified credit entries. Replace every example fact with evidence from your own project before treating it as complete.

Self-check

Complete these checks against the required result.

Read the title and overview without opening another file. Confirm that they identify the product, intended reader, and current result.
Close the browser and follow the written open procedure. Confirm that the expected result appears without an unstated step.
Use the documented structure to find the page content, styles, local assets, and complete test evidence.
Check each technical decision against the project and confirm that its reason describes a product effect.
Compare the verification summary with test-report.md. Remove any result that the report does not support.
Confirm that known limitations are specific and that unfinished work is not presented as complete.
Open every credit link and verify the source, license or permission, and stated modification.
Search README.md for passwords, tokens, private links, personal contact details, local account names, and absolute local paths. Remove any result.
At a narrow viewport and 200% zoom, confirm that code, paths, links, and tables remain readable without hiding required information.
Run git status and confirm that only the completed README changes remain before the documentation commit.

Record the documentation checkpoint

After the fresh-reader test and self-check pass, run from quality-profile:

git status
git diff
git add README.md
git diff --staged
git commit -m "Document quality profile project"
git push

Reload the private GitHub repository. Confirm that the README renders on the repository page and that its instructions and evidence links still describe the committed files.

Optional extensions

Next step or safe stopping point

Your website now has a tested result, committed documentation, and a private remote copy that another person can inspect with your permission. Keep quality-profile, test-report.md, and README.md together. In the next lesson, you will use this evidence to prepare and deliver a short product presentation.