A ticket is a short note that says one thing the app should do differently. Write it so someone who has never seen your screen could picture exactly what you mean, and know when it's done.
Every ticket follows the same shape. Same order, every time, so they're quick to read and easy to sort.
feat, fix or bug. See the three cards below.
Where in the app you are. Start with "On the Books page". If there's a tab, name it too: "On the Books page, Books tab".
Optional. Which part of the page: a button, a row, a menu. Use the words from the vocabulary section. Quote button words exactly as they appear: the "+ New Book" button.
One sentence, the main ask. Start with a doing word: add, replace, remove, move, rename, hide.
One short sentence per result. What does the person see or get after they do the thing? If something should not happen, say that too.
Something new. An ability the app doesn't have yet.
"Let me rename a book." Today there's no way to do it.
Works, but should be different. Nothing's broken; it just isn't how you want it.
"Show a trash can instead of the word Delete."
Something's wrong. It behaves in a way nobody would want: stuck, missing, crashes, wrong info.
"The menu stays open after the thing it belongs to is deleted."
Not sure if it's a fix or a feat? Pick one and move on. Jake would much rather get the ticket than a perfect label.
These are all about the Books page. The colors match the recipe above.
Why it works: it's a new ability, it names all three places the pencil goes, and "edit the name" says what the pencil is for. Could add: a result sentence, like "Pressing Enter saves the new name. Pressing Escape cancels."
Why it works: three clear results, and it spells out what gets deleted along with it. That's exactly the kind of thing a developer would otherwise have to guess. Could split: this is really two asks (the icon, and the type-to-confirm). One ticket is fine when they belong together; split when either could ship on its own.
Why it works: a good bug says what happens now and what should happen instead. Could add: the steps to make it happen, in order: "1. Open the series menu. 2. Delete the series. 3. Menu is still showing."
Why it works: button names are quoted exactly, and "before it's created" is the key detail. Could add: what "Cancel" does: "Cancel closes the popup and nothing is created." The developer word for this popup is a modal.
Why it works: it names the unwanted side effect. Saying what should not happen is just as useful as saying what should.
A pretend version of the Books page. Flip between Before (how it works today) and After (all five tickets done). Click the pencils, the trash cans, the ⋯ menu and the new buttons, and check each one against its ticket.
With all five tickets done. Everything in blue is new.
Fill in the blanks and the ticket writes itself. The checklist underneath tells you if something's missing.
When you read a ticket (yours or Jake's), you're checking one thing: could someone build this without asking a question? Run through these.
You don't need all the developer words. These are the ones that save the most back-and-forth. Everything below works, so poke at it.
An area that slides in from the side (or sits there) next to the page. You can still see and use the page.
Say: open the notes panel on the right
A popup box that sits on top of the page and dims everything behind it. You have to finish or cancel it before you can do anything else.
Say: show a modal asking for the book name
. Panel = beside. Modal = on top.
These three come together. The label names the box. The input field is the box you type in. Help text is the small grey hint underneath.
The grey words inside an empty box are a placeholder. They vanish when you type.
A tiny dark label that appears when you rest the mouse on something, usually an icon, to say what it does. Phones don't really have tooltips, since there's no mouse to rest.
Say: add a tooltip that says "Rename" on the pencil
A section is a chunk of the page about one topic, usually with a heading. A container is a visible box that holds things together. A section can have several containers in it.
You'll also hear card for a container that's one item, like each book box here.
A dropdown opens a list and you pick one. A multi-select lets you pick several, often shown as little pills.
A button does something once, right now. A toggle is a button that stays pushed in or popped out, like Bold in a word processor. A switch looks like a light switch and turns a setting on or off. People mix up toggle and switch; either word is fine as long as you say what it turns on.
A button that shows a small picture instead of words, like the pencil and trash can. It should have a tooltip so people know what it does.
The ⋯ one is often called a "more" menu or kebab menu.
Short for navigation bar. The strip, usually along the top (or bottom on phones), with links to the main pages. It stays the same on every page.
The highlighted link shows which page you're on. That's the active page.
A strip of buttons for things you can do right here, on this page or this item. Often it only appears after you select something.
Nav bar = go somewhere. Action bar = do something.
Something is hidden when it isn't on screen at all, and shown when it appears. Hidden things take up no space.
Say: hide the word count until I hover the chapter
A disabled control is still on screen but faded, and nothing happens when you click it. It becomes enabled once it's allowed. The delete box on the Books page works this way.
Hidden = gone. Disabled = there, but greyed out.
A section you can open to see more, then close to tuck away. Usually has a little arrow that turns. Also called an accordion when there are several stacked.
Say: series should start collapsed; click the arrow to expand
A list is a stack of similar items. Each item going across is a row. When the info lines up in vertical stripes, each stripe is a column, and the top row naming them is the header.
| Chapter ← column | Words | Last edited |
|---|---|---|
| The Lighthouse ← row | 2,310 | Tuesday |
| Driftwood | 1,845 | Monday |
| A Letter Arrives | 3,002 | Sep 20 |
Say: add a "Last edited" column to the chapter list
or on each chapter row, add…
The page rearranges itself to fit the screen. On a wide computer, things sit side by side. On a narrow phone, they stack and menus tuck away. Drag the slider to squeeze the pretend screen.
In a ticket: "On a phone, the buttons should stack instead of sitting side by side."
The page updates the moment something changes, without you reloading or pressing Save. Type below and watch.
In a ticket: "The word count should update as I type, not only after I save." Responsive = fits the screen. Reactive = keeps up with changes.
Both run on a phone. The difference is where they live.
In a ticket, say which one you were using: "On the Android app…" or "On my phone in Chrome…". They can behave differently.
Try each one on the pad below (use a phone for swipe and press & hold).
| Word | What it means | Where |
|---|---|---|
| Click | Press and let go with the mouse. | Computer |
| Tap | A click, but with a finger. | Phone |
| Press & hold | Keep your finger (or mouse) down for about a second. Often opens extra options. | Mostly phone |
| Swipe | Slide your finger across. E.g. swipe a row left to show a trash can. | Phone |
| Hover | Rest the mouse on something without clicking. Shows tooltips. Phones can't hover. | Computer only |
Tickets often start with "On click, …" or "On tap, …". That just means "when someone clicks (or taps) this".
Which edge things line up against. Most reading text is left aligned. Titles are sometimes centered. Buttons like Save often sit on the right.
The tide came in slowly that morning, the way it always did in late autumn.
In a ticket: "Right align the Save and Cancel buttons at the bottom of the modal."