Codify the Specs
"Codify," in the context of writing down ideas, refers to the process of systematically organizing, structuring, and documenting thoughts, concepts, or principles into a clear and coherent written form. It involves creating a formalized and easily understandable representation of ideas, often using language, diagrams, or other forms of communication. Codifying ideas can make them more accessible, shareable, and usable for both personal reference and communication with others. It helps ensure that the essence of the ideas is captured and can be effectively conveyed and understood.
In the context of computer programming, "Specs" is a commonly used abbreviation for "specifications." Specifications, often referred to as specs, are detailed descriptions or documentation that outline the expected behavior, functionality, and requirements of a computer program or software component. They serve as a blueprint or roadmap for software development and help software engineers, developers, and stakeholders understand how a program should function, what features it should have, and what criteria it needs to meet.
When you find yourself in the phase of developing a feature for your product, with well-defined high-level concepts and scenarios unfolding, there's often a critical juncture where you hand over the specifications to the developers and trust that they can grasp and implement the product owner's language. This phase can be challenging and relies heavily on mutual trust. I believe there's a structured approach to navigate this transition, and it's referred to as “Codifying the Specs.”
Behavior Driven Development with SpecFlow
I use SpecFlow because I’m a .Net developer, but you can use any BDD tools you like. Here’s the checklist for navigating this patch of choppy water.
Take the specs-as-docs and code them up as feature files.
Back-link and verify everyone agrees the behaviors are correct.
Start tracking any changes to the specs in version control in the same repo as the app code.
Use Gherkin Syntax
Write these scenarios in Gherkin syntax. Gherkin is a structured language used in BDD to define scenarios in a human-readable format. It typically includes keywords like "Given," "When," and "Then" to describe the steps of a scenario.
Create Feature Files
Organize the Gherkin scenarios into feature files. Each feature file typically corresponds to a specific feature or functionality of the software. Feature files serve as a container for related scenarios. In the feature files, define the steps of the scenarios using Gherkin. These steps should be written in plain language and should be clear and specific. Each step corresponds to an action or verification point in the scenario.
Create Tickets for Features
Creating feature tickets for each feature file is a good practice to manage and track the development of individual features in your software project. Include a link to the feature file in the ticket, copy the scenario description as the ticket description, and make a checklist in the ticket that includes each behavior that needs to be coded.
Link-O-Rama All-the-things!
Make sure you leave breadcrumbs in all the docs you touch during this process. The death of many a good feature is too many copies of specs. To avoid this, use links.
When creating a feature file, make sure to include a reference link in the original word-processing document. This can allow for deeper understanding of the feature beyond the spec.
After creating a feature file, make sure to commit it to the repository and include a reference link in the original word-processing document. While not everyone may have direct access to the link, providing a link along with a note indicating the new location of the specification can initiate a discussion
When creating a work ticket, add a link to said ticket to the notes of the spec file, as well as a link to the spec in the ticket.
Conclusion
In this post, I have shared my approach to “codifying the specs”, which is a structured way of translating the specifications of a software feature into scenarios using BDD tools and Gherkin syntax. By codifying the specs, I can ensure that the developers and the product owners are on the same page, that the specs are version-controlled and up-to-date, and that the scenarios can be used as automated tests for the software. Codifying the specs is not only a good practice for software development, but also a useful skill for communicating ideas effectively and clearly. I hope you find this post helpful and I encourage you to try out codifying the specs for your own projects.