</rant>
ChatGPT is a great tool for creating and re-formatting content based on text that it’s given, but for the purpose of writing technical documentation, it can be hit and miss.
I’ve found it great at re-ordering notes and formatting them in a way that can actually be understood – great when it’s a Monday night, you’ve taken multiple shots of espresso, and are trying to stay awake so you can get some Jira tickets out and ready to assign on Tuesday.
Not so great when you only know the general outline of the process, and try to get ChatGPT to fill in details about an implementation that may not have been fully thought out.
Writing a good story takes a conscious effort, and the one writing it needs to know the entire context of the application, use terminology that’s consistent to the rest of the application, and ensure that each part of the story lines up with the rest.
Unless you’ve trained ChatGPT on all of the documentation for your application (you do have documentation, right?), AND the format and terminology you use in your stories, you’re going to end up with confusion when the language ChatGPT uses differs from what’s been used in reality in your application.
</endrant>
Writing stories for software development can be a tricky process. If done correctly, you can minimize the number of questions and meetings that are sometimes needed to provide context or motivation for the feature. A good story should have the following:
- Motivation – the reason the feature is being added, and who it’s for.
This is generally the first and last part of a story – “As <x user [in y situation]> …. so that I can accomplish <z>” - Business Rules – The meat of the story, describing the way the feature works, and how the user interacts with it.
- Technical Outline – Any technical information useful specifically to the developer. It can help the developer find a good starting point or base to plan from.
(this is typically outside the structure of the story itself)
Example: Building a Todo List App
Consider the following story, and each section of it:
As a client using the todo app software, I want to be able to create todo items that can have an editable title, description, and due date, so that I can plan tasks that need to be done, along with getting them done by a specific due date.
Motivation
This is the “why” of the story, and the “who” it applies to. It doesn’t directly relate to the feature details itself, but provides context of what type of user is using the feature, the situation they’re in (context), and the issue they’re trying to solve (or goal to accomplish) with using the feature:
As a client using the todo app software, I want to be able to create todo items that can have an editable title, description, and due date, so that I can plan tasks that need to be done, along with getting them done by a specific due date.
By providing motivation and context, you are helping the developer make good UI choices and QOL additions that help the user accomplish the goal, and know where the user’s path will start in the app.
There is also the added bonus of helping whoever is writing the story realize if the feature is absolutely necessary, and if the feature is really going to solve the pain points or succeed in their goal as it’s written. This is helpful to prevent tunnel vision from causing the feature to stray to far from the path of what’s realistic and helpful.
It’s also helpful for the person writing the story. If the first two parts of the story don’t make sense (as X person, I want to be able to do Y) in accomplishing the goal, then the feature is either not necessary or the business rules need to be modified.
It’s also helpful in slimming down or splitting a story. If the final goal of the user is to “plan tasks that need to be done, and get them done by a due date”, and the feature included “create todo items with a title, description, and attachments”, maybe the photo upload isn’t necessary for that version of the story, but could be split into a second story, where the goal of the user is to add additional context or decoration to a todo item.
Business Rules
The description of the feature itself, and how it’s supposed to work. Really the “meat” of the story. The feature should allow for all of the rules described.
I want to be able to create todo items that can have an editable title, description, and due date.
If someone else is testing the feature, this is the portion that the feature needs to follow in order to be considered working and complete.
Technical Outline
This one isn’t technically part of the scrum process, but something I like to add. It’s not really necessary if you’re the one writing stories and implementing them, but can be extremely important if the story is being handed off to another developer, especially if the developer isn’t entirely familiar with the framework of the app.
Given the previous story written above, here’s what I might append in the story (or story comments) to help a developer get started:
“todo” items are stored in the “Todo” database table. Use the “TodoController” class to create/update todo item records. Endpoints will need to be added to allow the frontend to communicate with the controller, check out the “LabelEndpoint” class as an example of endpoints can mutate objects in a secure way.
Ensure that when the user is updating todo items, they have access to the todo item (check out usages of the “PermissionsManager” class for how relationships and access can be validated).
By providing a technical outline and starting point, you can help kickstart the development effort. It’s extremely important if part of the development feature is already done or can be re-used from another spot, so you can avoid duplicating effort. By also providing references to how a similar existing feature exists, you can ensure consistency in code and reduce development time by providing a similar pattern to follow.