Does anyone have advice on writing backend / API tickets? UX is really good at specing out frontend work with designs and requirements. However, writing backend is harder and tends to vague tickets. I’d like the ticket to be more than “create backend support for new feature.” but avoid writing out super detailed technical specs. Sometimes you don’t know the full implication of the ticket/work before you start so detailed specs are impossible to write. Should this be exploratory work done outside of JIRA? Is this part of the shaping process, for Shape Up fans (I am one)?
Any strategy or workflows or ideas would be appreciated. Thank you.
11 Likes
I’d suggest:
- Super high-level description of what functionality is being considered app-wise.It may not be clear initially where the appropriate functionality lay.
- A discovery process where someone works with product and other stakeholders (e.g. front-end teams, etc) to understand the intended outcome, propose a solution, and gather feedback on that solution. This phase could include an implementation spike (e.g. quick & dirty prototype or swagger spec).
- Once it’s scoped, it can be broken down into its constituent parts (if needed) and then implemented. There are a few ways to do this from an organizational perspective based on the size of the project.
What’s most important here though, is that the communication is occurring prior to implementation / that everyone is on the same page about what’s being implemented & that it satisfies whatever the stated goals are of the work.
10 Likes
I have struggled with this in the past but I have over time taken a systems approach to it. All backend systems at the end of the day can be seen as a combination of smaller microservices or systems coming together to achieve a larger objective. The way I do my work breakdown is:
- What are the core services that constitute the backend system? (This is your epic or high-level umbrella feature)
- What is the intended goal or process each service needs to achieve - its primary function? (This becomes a sub-tasks for each epic)
- What are the inputs and outputs of each service( this becomes a sub-task and your outputs become dependencies for other systems)?
- What are fail-safe or error handling mechanisms? (This becomes a task).
- What is the success criteria or test checklist to determine if a service is doing what it is intended to do( this becomes your sign-off or validation task).
You fill out the above checklist as you go through technical discovery with your engineering team. It has served me well in the past and still does today.
10 Likes
If the tickets get into implementation detail (ex. create endpoint X with service Y) then I’d imagine that’s a senior engineer’s job. they can give junior eng the goal of designing implementation and then advise on how to improve the design until it is ready to implement. mentorship built-in.
if it’s a small team full of competent senior engineers, they may not need a detailed ticket, but rather just need to discuss high-level design amongst themselves before they build it.
8 Likes
Regularly… the expressed objectives change as the organization (group/organization/whatever) better gets what it is that they’re attempting to do.
3 Likes
The vast majority of designing is tied in with sorting out what usefulness is required, where that usefulness ought to live, and how that usefulness ought to be tried and kept up with. The test is in well… getting everybody in total agreement on what those things ought to be and resemble.
3 Likes
Happy to answer any questions / provide more clarity as needed. This was a pretty high-level answer to your question.
3 Likes
Composing the operation and afterward perusing your reactions, correspondence is truly key. On the off chance that you can just compose a title of a jira ticket, it presumably implies the group doesn’t comprehend the issue. Then, at that point, a discussion is required, even a short one, in the event that somebody in the group has a reasonable arrangement, and we simply need to get it reported.
3 Likes
Precisely, it truly comes down to if you are presenting new ideas and how all around displayed the code base is to the new idea that you are attempting to execute.
For instance, adding one more language to an i18n application could be straightforward if the language records as of now exist and have been given. Adding i18n without any preparation is doubtlessly a great deal of work!
3 Likes
I don’t know if I did it the right way, but I was always a fan of technical products. I can share what worked for me/our team. We owned a new technical platform used by multi-channels (i.e. apps).
The way we approached it was to do user stories for backend still from a user’s perspective.
An example is the easiest way I can explain, so I’ll share what I can with masking anything confidential.
- We map out all the “what” users need to be able to do across all channels apps.
- We identify the common (across all users) and unique (for one user type) “what” needs (on backend (i.e. our technical product, service/capability)
- We write our user stories of what the user (common or unique) must be able to do. Included would be all the scenarios, outcomes, and examples (p.s. I find the examples to be the most valuable for communizing to any team)
- We work with tech to figure out the best solution on the backend (i.e. the technical platform understand the needs of all channels, users, how they might evolve to prepare for the next feature)
I hope this helps a bit. Let me know if you have any specific questions
1 Like
My question is, for step 4 when you “figure out the best solution on the backend”, what is your process like? How do you document and track the work?
2 Likes
I’ll attempt to draw out a speedy model later. The fast answer is a tech modeler drafts a framework engineering arrangement dependent on the necessities.
We then, at that point, work together to see how it achieves all the “what” needs.
We compose significant level stories from the “what” needs. We meet with tech curve and tech prompts to see how they need to foster an arrangement to execute the arrangement in fourteen-day pieces. Then, at that point, we make the narratives nitty-gritty/breakdown to coordinate with the conveyance plan.
1 Like
Or if you give me a high-level example from the space you’re in, I can try an example in that
A lot of great comments here, I will just add my two cents.
- Flow chart is a great place to start. Helps you understand the decision tree. Also easier in the context of APIs, since they tend to have true I/O quality. I have attached a sample from a ticket I created recently.
- I highly recommend getting familiar with HTTP status codes. This separates the pros from the rest. Making sure you’re providing the right status for failures (or otherwise) is very nice and will redound to your benefit in the future. In many cases, I will have declarative lines like “When the record is not found, send a 400 error.” in the ticket itself.
- OAS3 is a great way to define the contours of the API before you build. On top of that, you can use it for validation inside the code. This not only helps you document a bit more upfront, but it gives you a nice tool to ensure the contract later.
This topic was automatically closed 180 days after the last reply. New replies are no longer allowed.