Write Project Documentation with Markdown

What is Markdown, and why use it?

Markdown is plain text with a few readable symbols. GitHub turns those symbols into headings, links, lists, tables, and code blocks. The same file stays useful in an editor, a pull request, and on GitHub.

In a project, documentation is part of the product: it tells the next developer how to run the app, what an API expects, and how to contribute safely. Start with a README.md in the repository root; create focused files in docs/ as the project grows.

Create your first Markdown file

Make a file called README.md. The .md extension tells GitHub and many editors to render it as Markdown. Add this example, save it, then preview it in VS Code or on a GitHub branch.

# Todo API

A small API for managing tasks.

## Run locally

1. Install the .NET SDK.
2. Run `dotnet run` from `backend/TodoApi`.
3. Open `http://localhost:5000/scalar/v1`.

Use one level-1 heading (#) per document. Then use ## and ### to show the structure below it.

The Markdown building blocks

Links should say where they go

Prefer [Install Node.js](https://nodejs.org/) over [click here](https://nodejs.org/). Descriptive link text is easier to scan and still makes sense out of context.

Show commands and code clearly

Put a single command, filename, HTTP method, or value in inline code. Put multi-line commands in a fenced code block, and name the language after the opening fence when possible for syntax coloring.

\`\`\`bash
npm install
npm run dev
\`\`\`

\`\`\`json
{ "title": "Learn Markdown", "isCompleted": false }
\`\`\`

Every command should include its context: the directory to open, required environment variables, expected URL or output, and how to stop or undo the action. Never include real passwords, access tokens, or private connection strings in examples.

A README that helps people start

1. Name and one-sentence purpose — what problem does it solve?
2. Features — main user-visible capabilities.
3. Requirements — runtime, SDK, database, and accounts needed.
4. Quick start — exact install and run commands.
5. Configuration — variable names and safe example values.
6. Usage or API examples — show one successful path.
7. Testing and troubleshooting — how to verify and common fixes.
8. Contributing and license — how changes are proposed and shared.

Keep the README as the front door. Move long tutorials, design decisions, and API reference material to docs/, then link to them from the README.

Write for the reader who was not in the room

• Start with the reader's goal, then give the smallest working path.
• Use short headings that answer a question: How do I run it?, not Miscellaneous.
• Prefer concrete examples: real file paths, routes, and expected results.
• Separate required steps from optional enhancements.
• Keep terminology consistent: do not switch between “task”, “todo”, and “item” for the same entity.
• Link to the authoritative source instead of copying a dependency's full manual.
• Update docs in the same pull request as the behavior they describe.

Documentation is versioned too

When the API route, environment variable, or setup command changes, update its Markdown in the same branch. Reviewers should be able to compare the code change and its instructions together.

Markdown review checklist

• There is one clear title and a predictable heading hierarchy.
• Links work and their text explains the destination.
• Commands can be copied exactly, with the required directory stated.
• Examples use safe placeholder secrets such as YOUR_TOKEN.
• The page explains the expected result, not only the action.
• New terms are introduced before they are used.
• The page is easy to skim: short paragraphs, lists, and focused sections.

For the complete syntax reference, see GitHub Docs: Writing on GitHub.