Writing Tickets for Software Engineers | Nick HaydenTickets are the most common unit of work I use as a software engineer, they often come from a product manager, program manager or even other engineers. In my time being a contractor, engineering manager and full time team member I have seen several styles for writing tickets not all of them good. This post is my attempt to write what I believe to be good practice when writing tickets and the minimum fields required in the hopes that your journey in software engineering is efficient, tickets are not wasted and your work remains high quality.<br>The fields needed for ticketing is often less than consultants would have you believe. The best form of ticket creation is the one used by the team, adding many fields and locked workflows can serve to prevent ticket creation and thus lose work that is needed for your application. Simply having title, description, status and due dates is enough to get the message across on where and when work should be completed. Anything additional is up to the individual organization. It is important to trust the entire team, if a person is making poorly formed tickets it is better to train that individual rather than slow everyone else down with more process.<br>The skill of the engineer will often be your determining factor when it comes to how much detail should be added to a ticket. Don&rsquo;t be fooled though, just because someone is more experienced does not mean they can intuit context that does not exist. A ticket&rsquo;s description or goal should be defined by acceptance criteria. This criteria is best when it is concise, perhaps bullet pointed and, has a clear result. Acceptance Criteria such as &ldquo;User can book a room&rdquo; for a hotel app is too vague and should be broken down further. When criteria is that broad there is too much room for interpretation, a user could book a room via SSH but I doubt that is what the ticket creator is expecting, thus it is important the acceptance criteria is a blend from engineering, product and design.<br>Designs and Documentation<br>When providing designs in tickets it is best to include an image of the completed ticket so engineers looking at the ticket for the first time can make a rapid assessment of the work involved. This image should be used for information only and not the design reference itself which should live in whatever design tool the team uses e.g. Figma. By giving the latest design links to the engineers the team can avoid rework if designs change during the development phase. If a design changes after work has begun it is critical that the team is informed directly in-person as well as the ticket being updated and in some cases a new ticket being made that supercedes the original. Rebuilding something after a large design change is the source of many project overruns, and it is not enough to expect engineers to check Figma and understand what has changed without being informed especially if they have already completed that work and may not be checking it again.<br>In the same way as design, engineering documentation must live both in and out of the ticket. Many teams use wikis like Notion and Confluence to store their longer term documentation. This is a good choice since these wiki platforms often have better search than ticketing platforms and can be linked to other documentation that may not live in the same place as tickets e.g. strategy documents and product roadmaps. It is dangerous to include much of a document without including all of it since an engineer will read the ticket, assume they have the information and move on even if that ticketed documentation is now out of date and the main document has been updated.<br>Assigning Tickets<br>Assigning tickets should be easy. A ticket should be assigned to the least skilled engineer that can complete the task. If you are assigning a simple ticket to change the color of a button to your most senior engineer you either do not have difficult enough work or you are procrastinating on more difficult tasks. Over time your engineers should become more skilled and able to handle more difficult work, this is a two part challenge, you must first assign them work just out of their skillset&rsquo;s range so they can face and overcome difficulty, secondly you should give them a healthy amount of work within their skillset so that they can master their current level. It is only by frequently solving problems are we able to solve them faster. Assigning tickets can be done by anyone, it should not be controversial that an engineer assigns a ticket to someone or that a product manager assigns it back. Who ever is currently assigned to the ticket is the owner of that ticket, in this way, ownership changes frequently as work travels through the pipeline. Anything assigned to an engineer should be in a work-ready state with no blockers prior to starting, if a ticket is not in a work-ready state it must be assigned to the person that can unblock it....