Bug reports, change descriptions, asking for help

Why this matters

Three kinds of writing dominate a technical team's day, and each has a shape that makes it work. Getting them right is the fastest way to be someone colleagues like working with, and it is entirely learnable.

A bug report someone can act on

Six parts. Miss one and the first reply is a question rather than a fix.

## What I did

Ran `python3 src/trailguide.py --list` on a fresh clone of `main`.

## Expected

A table of ten trails.

## Actual

    Traceback (most recent call last):
      File "src/trailguide.py", line 41, in main
        km = float(row["distance_km"])
    ValueError: could not convert string to float: ''

## Where

Commit d3b92ec, macOS 15.1, Python 3.12.

## How often

Every time, since I added a trail with an empty distance to `data/trails.csv`.

Two rules carry most of the value. Paste text, not screenshots, for anything that is text: it can be searched, copied into a test and quoted in a fix. And say where, precisely: a file, a version, a commit, a URL. "The FAQ is wrong" costs someone ten minutes of hunting before any work starts.

A change description a reviewer can use

Four parts, and the reviewer needs nothing else (lesson 9.7):

## What

Adds the Windows steps to the installation guide, and links them from the FAQ.

## Why

Support gets this question weekly; issue #12 has three examples.

## How to check

Follow `docs/getting-started.md` on Windows, or read the rendered preview.

Closes #12

What in one sentence, why with evidence, how to check so the reviewer can verify rather than trust, and the closing keyword so the issue closes itself. If your project has a template, fill in its headings rather than replacing them.

The commonest failure is a description that repeats the diff: "changed getting-started.md" tells the reviewer what they can already see and nothing they need.

Asking a Git question that gets answered

Git questions get slow answers when they lack state. Include four things and the answer usually arrives in one reply:

1. What you were trying to do, in plain words: "get my branch up to date with main".
2. The exact command you ran, copied, not retyped.
3. The exact output, in a code block, including the hints Git printed.
4. The state: the output of git status and git log --oneline -3.

I'm trying to update my branch from main. I ran:

    git push

and got:

     ! [rejected]  docs/12-windows -> docs/12-windows (non-fast-forward)
    error: failed to push some refs

`git status` says:

    On branch docs/12-windows
    Your branch and 'origin/docs/12-windows' have diverged,
    and have 1 and 1 different commits each.

What should I do?

That question is answerable in one line. The same question as "my push isn't working, any ideas?" takes four messages to reach the same point.

Say what you have already tried, too. It saves the answerer suggesting it and tells them how you are thinking.

Where to ask

The principle: ask where the answer will be found again. A Git question answered in a private message helps one person once; the same answer in the merge request helps everyone who reads it later, including you in six months.

How to do it

$ git status
$ git log --oneline -3
$ git branch -vv

Common mistakes

• A screenshot of text. It cannot be searched, copied or quoted.
• "It doesn't work." Which command, on what, with what output.
• Omitting git status from a Git question, which is the first thing anyone will ask for.
• A change description that restates the diff.
• Asking in chat where the answer disappears.
• Not saying what you already tried.
• Retyping error text rather than copying it, which introduces mistakes into the one part that must be exact.