· architecture · 9 min read
Build Prep - Writing Stories
Introduction
Ok, we have done our discovery, got our design, and thought through the architecture, LET’S DO THIS THING!… Wait, pump the brakes. Not so fast Speedy Gonzalez. You are not ready to start building the site just yet.
Planning a site is more than just the design and architecture phases I previously spoke about. Your plan needs more than an outline to guide you. It needs something that will help keep you on track. Something that will let you not forget all the things that you need to do along the way. What you need are stories.
“WHAT? Stories??? I am not writing a book here. I am building a website thank you very much.” Hold up! Yes, you are building a website. But you need a complete plan to track all the important pieces of your building process so that you stay organized and don’t have a lot of rework. The way we handle this is called writing stories. This is part of the project planning process. Normally we have a project manager or business analyst writing these. But anyone can and developers should be a part of this process.
Writing Stories
“So how DO I write a story?” you may ask. It’s actually quite easy. You need to take time to think of your next steps. What needs to be done before what else. Then you need to break that down into small manageable tasks. For example, your very first task should be to setup your GIT repo. For this just write a story or task titled “Setup GIT repo”. Then to the body of the story, you add further details such as the repo name to use, who to give access to (and at what level), and where to set it up (self-hosted, Github, Gitlab, Bitbucket, etc).
Writing stories shouldn’t just stop at a title and body. You should categorize your stories or organize them into epics. You should also assign points to your stories. “Points? What are those?” glad you asked. Points is a numerical value you assign to your stories to gauge the level of effort. This is important for project planning to track to make sure developers are not spinning their wheels and continue to make progress. Even if you are the only developer doing this for your own projects this can be useful information and a useful way to keep yourself in check.
Pointing
You are probably wondering how pointing works. First, what scale do you want to use and how does the scale work? In standard scrum practices, we use Fibonacci sequences of numbers to point or weight stories. The sequence goes like this: 1, 2, 3, 5, 8, 13, 21… Often times teams will even add a half-point option for the insanely small things such as changing a color value somewhere.
Ok, so we are using Fibonacci numbers now. How do they apply? Well, this is up to you and your team really. But generally what I have seen is that 1 is the absolute easiest tasks and takes almost no time at all. A 2 is something simple but has a modicum of complexity and time to it. A 3 is complex enough that you will probably spend a day or more on it. A 5 is pretty complex and will probably take up the better part of your week. An 8 is starting to get a bit too big and you need to start considering breaking this down into multiple stories, making this story an epic. An 8 will probably take up most of a sprint.
Then there is the vaunted 13. Once you start getting this big you either don’t understand the problem or you need to break it down into a lot of little tasks. Don’t even get me started on a 21. If you don’t understand the problem then you probably need a Research Spike story, which is just time and effort that is dedicated to researching and understanding a task or problem enough to plan the work for it. This spike should be pointed to itself. Once completed you can then create your manageable-sized tasks.
If you do even a modicum of research on sprint planning and scrum/agile project management you will know that they frown upon using time as a reference for your point scale, but ultimately this is where people go because they need a frame of reference. Just keep in mind that this is more about complexity and effort. Not about time. Once you and your team have got a few tasks under your belt then you can use prior tasks as your frame of reference. Ultimately this is where you want to get to.
What’s Next?
Ok, we have an understanding of pointing and writing a basic story, what’s next? Next, we need to start writing our stories. Sit down and think through your next steps at a high level then write those down somewhere. Then take those and break them down into multiple smaller steps. Then break those down even further if needed.
What I like to start off with is just thinking “ok, what do I need to get rolling with this site?” and start writing those stories. First, I have to setup my local environment. Great! How do I do that? Well, I need to choose the tools I am going to use. Going into a project I will have some assumptions on the tools I need so let’s skip that decision process for now.
I know, for example, that I am going to use Docksal for my local environment. I need to set that up. But wait, before I can set that up, I need my GIT repo setup (as previously discussed) so that I can save and track my work (code-side). Write a story for that.
Next, I need to configure Docksal. But in my case, I am going to start with a powerful site skeleton called Drupal KIT. KIT is a basic configuration of Drupal that is slightly opinionated and provides tools to help us get setup faster. As part of this, it comes preconfigured with Docksal, perfect! This saves me that step. So the next story will be to download KIT into your newly created repository. Worded like this: “Copy Drupal KIT into repo”. The body might contain a link to find KIT.
Then you have to actually configure your website. For this, I create a series of stories. Things like “Customize KIT for project” and “Setup initial theme” and “Initialize the database. From there you can break it down even further. As an example, I have a list of the first 12 stories that I wrote for this project:
Create base site implementation with KIT and Docksal.
Create an initial custom theme setup.
Theme: Configure fonts and font families.
Theme: Setup Bootstrap.
Theme: Configure Colors.
Theme: Configure default font sizing, styles, and colors for all base tag types.
Theme: Configure Regions.
Site Config: Create the Categories taxonomy.
Site Config: Create the Tags taxonomy.
Site Config: Content Types - Create the Article content type.
Site Config: Content Types - Create the Course content type.
Site Config: Content Types - Create the Lesson content type.
As you can see, this is not an exhaustive list. It’s enough to get started and that is exactly what I want. After I get through most of these stories I will start writing more for the next tasks to do. This is a common practice and often there will be sprint planning sessions where we determine what we work on next. Before this the project manager will write the next set of stories and give the developers a chance to review and point them.
Tools
“Ok, I’m ready to start writing stories. But where do I write them down?” great question. For project planning, you need a tool to organize all the activities of your project. The one I am most familiar with is JIRA from Atlassian (the same company that creates Bitbucket). I also know that both Github and Gitlab provide these types of tools. You can also use third-party tools that don’t come bundled with your GIT hosting service. I prefer bundling myself, for simplicity and interconnectedness. I also don’t want to pay anything for the service in the early stages until I get money coming in.
For my part, I am choosing Gitlab because I have long wanted to try the list of tools and features that they have. They also offer some cool CI/CD tools, lots of build hours for free, private GIT hosting for free, and lots of other nice-to-haves. You will have to do your own research and explore the options for your needs.
How do stories work?
You should build a backlog of stories to work on. Once you are ready to get going you put the story you are working on into the “In Progress” lane of your tool then start working on it and leave any comments you might need. Then, when you merge in your code and deploy it to your test environment you can then put it into “Ready for QA”. QA can then review and either kick it back or set it to “Done” or “Ready to Deploy”.
The exact states for your tickets are up to you and your team, but the states mentioned above are pretty common. As you finish stories you can see how quickly you progressed through the work and build a velocity to your efforts. This metric can be useful to make sure the team is on track.
Conclusion
In conclusion, writing stories is a simple and powerful way to organize and track your work and all the activities related to your project. It is also a process and a practice that all good developers follow. If you fail to plan, you plan to fail.