by Ian Villeda

Strong technical writing is a critical skill for everyone involved in making software. Clear, well-formulated tickets foster clear communication, transparency, healthy collaboration, and strong institutional memory for the broader organization. The following is a rough guide on how to write clear technical tickets that facilitate collaboration, transparency, and fun.

Structure: What to include & what not to

• Make it clear to the reader (a) what the task is and (b) what its completion criteria are. This is your ticket's one and only job.
• End your ticket with Next Actions. Your reader needs to walk away with a clear understanding of what happens now that they’ve read the ticket: how to get started, which teammates are completing each next action, and optionally when those teammates should have those next actions completed.
• Create only one ticket per task or project. If a project has many sub-tasks, break each of those out into their own ticket, linking back to a main ticket that describes the broader task
• Use the inverted pyramid & don't bury the lede when providing context or explaining complexity. State the most relevant “headline” information up front followed by any supporting details. If your reader stops reading your ticket halfway through, they should still have a general understanding of the task or problem you’re describing.
• Link out to background where possible. Link to other tickets, internal wikis, or documentation where possible rather than replicating that information in your ticket.

For projects where your audience may not have full context on what the problem is or why it needs solving, you may find yourself writing longer tickets. It's often helpful to separate these into sections, each with their own heading, e.g.

• Background context including deadlines, deliverables, & project constraints
• What the problem is
• Why it needs solving
• How you intend to solve it, even if it's soliciting ideas from teammates
• Who will work on what, how you will distribute work
• Next actions

For longer tickets you may also find it helpful to add a tl;dr at the top summarizing the problem & the work to be completed in a single simple sentence or two. This will signpost to the reader what to expect and when to read the rest of the ticket.