9 Ideas for More Useful Feature Specs
Joel Spolsky has written endlessly about speccing and why it’s important. According to him, skipping a spec is the “single biggest unnecessary risk you take in a software project.” Actually, it seems that almost every flavor of PM out there (project, product, program, etc) has an opinion on specs — like this guy. And this guy. And this guy and this guy .
However, the DALI spec, like DALI itself, is a unique creature. In The Real World™ one of the multitude of different types of specs might be written for a 4-month project. In DALI, a spec lasts 10 weeks. The Real World™ can have communication struggles between different departments and a spec can be a great way to notify the necessary stakeholders that a project is underway. At DALI, it’s pretty difficult to not know which project you’re on, but it’s easy to miss a design element because the designers were working at 10PM on a Sunday night. Since DALI has its own set of challenges, it only makes sense that DALI gets its own article for writing more useful specs.
I say more useful specs. Not “better” specs. I guarantee you that I can’t write the most high-fluting, eloquent spec in the world. But even if I could, it would serve the same function as any other spec: to help the team get things done. If my super duper spec doesn’t achieve that purpose, it’s probably not worth the time. In fact, there’s a good chance that it’ll get thrown into the abyss of Google Drive, never to be opened again. If none of these ideas help your team, they’re also not worth the time. Simple as that.
So, without further ado: 9 ideas for writing a more useful feature spec.
1. The spec should be tailored to your team.
Don’t exclusively follow a template! If your team needs to discuss something more technical, like telemetry or error cases, go ahead and do that in the spec. Conversely, if the deliverable is going to be shown to thousands of people at a conference, maybe your team could write a section on branding. There should be absolutely no “blank” sections, though. Blank sections happen when the team is following a template too closely and isn’t thinking enough about what parts of the project merit ideation. It’s better to take out blank sections entirely.
2. Determine how in-depth the spec needs to be.
Product specs tell a team what to do, not how to do it. Functional specs tell a team how to do it, assuming what to do has already been explained by a product spec. There are plenty of other types of specs out there (see this explanation if you’re curious).
At DALI, the feature spec is a strange kind of hybrid. It’s up to your team to determine the level of detail you reach. However, in my experience teams tend to push towards the technical side from the perspective of the product without thinking enough about the end user.
Maybe your team has figured out every single component in the project, down to the last button and breadcrumb. Lucky you! In every other case, individual components should be left to the Zenhub board, after multiple firm iterations.
For example, let’s say I’m on a new DALI project. Our goal is to build a website that will help the partner sell their handmade ugly Christmas sweaters. Call it…. SantaSweaties. The SantaSweaties team is in the process of writing their feature spec, and one of the requirements I have so far is this:
“Build a profile page.”
Every website has a profile page, right? Our website needs one too!
Unfortunately, I just wrote a requirement that’s limiting our success. First, it assumes that all profile information should be in a page. What if the profile is better represented in a tab? In general, DALI teams write the feature spec around week 3. The paper mocks might not even be done by then, let alone a decision that a profile user requirement should be a page.
Secondly, the sentence focuses on the app, not the user. In fact, it completely ignores the users that we’re building for in the first place. Which leads to the next idea —
3. Specs should be user-driven.
At a high level, focus on writing for user end goals instead of requirements. Besides resulting in a better product for the user, it also makes priority-setting easier. Don’t spend time filling in every detail of a feature if it doesn’t solve a problem for either a stakeholder or an end user.
DALI’s a pretty Agile place, and Agile development puts users first with the concept of user stories. A user story describes an end goal for someone using your project, in a way that a user would understand. That means no overly technical language and nothing oddly specific. The user stories can later be copied and pasted into Zenhub, with more discussion on how to achieve these user stories to follow in the comments. They often follow a similar sentence structure:
“As a ______, I can _________ to/so ________.”
For example, one Agile way of representing the user need behind my profile page requirements would be something like,
“As an end user, I can access my profile information from the main screen to view and edit my credentials before purchasing.”
From here, we can delve more into a functional spec-style delineation of exactly what the user story entails from a technical standpoint. But the framing of the user is absolutely paramount.
In doing this, we’re attempting to better understand how the users defined in the user personas would interact with our webpage. When does the user access profile information? And how? Sure, we could answer those questions with normal requirements — but this way, we’re not letting the user out of our sights for a single second. If you want a better explanation of user stories, feel free to check out this article written by a “chaos muppet.” Whatever that means.
4. Write the Happy Path.
The Happy Path is the story about an imaginary user and their absolutely perfect interaction with your project. Designers, and in my opinion the rest of the team as well, should be writing this during Week 3 (it’s under “Connecting Features” in the DALI Build page). Put it in your spec! Not only does this force the team to compare the user’s interactions with your proposed features and fix discrepancies, but it also makes it harder to forget the perfect user story during Week 8.5 when finals are looming, you’re in a rush to finish a component before your partner meeting, and you’re running on 2 hours of sleep in 5 days. The Happy Path will always be there for you in such troubling times. :)
5. Number your requirements.
Our specs here are normally pretty short, which makes this less of an issue. However, If you put mockups, the happy path, or anything involving your requirements in different parts of the spec, you can just add the number pertaining to that requirement at the end of the sentence. If you’re using MS Word, you can use its reference features. If you’re using GDrive, you could highlight the number and make it a different color. There’s a few reasons why you might do this:
a. If your team reaches crunch time and decides it needs to cut some features, you can search for all instances of that requirement number and cross out those sentences.
b. It’s easier to search for information related to a particular requirement.
c. If your team delegates requirements to different members, you can highlight each occurrence of a requirement number and highlight accordingly.
6. Write a set of potential problems. Write a separate set of open issues.
There are some problems that can be fixed, and some that can’t. For example, getting the look and feel of SantaSweaties is something my team can control. The spike in site traffic and potential crashes during holiday season is a potential problem that the team might not be able to address in 10 weeks and with limited experience with handling web traffic. That’s a good thing to list in a feature spec and potentially discuss down the line. Similarly, during the term there are going to be bugs and other issues that just aren’t worth fixing. Were there not enough female children between the ages of 2 and 4 in Hanover to interview during user research? That’s an open issue. Are the margins 3 pixels too wide when viewed on an iPhone 6? That’s another open issue.
If your project gets renewed for another term or gets picked up by your partner after it leaves the lab, listing potential roadblocks ahead of time will save next term’s project members some headaches.
7. Be aware of language.
This fellow I met with at an internship wrote super long specs where each requirement was described as if it were part of a UN committee proposal. Should, shall, and may were in every requirement. He told me that it was to help the developers establish priority in the event that they had to drop some features.
I’m not entirely sure whether such a ham-fisted approach would do much good here at DALI. But he was definitely on to something — how things are worded will say a lot to future teams who pick up your spec after your term ends. Your partner might also read the feature spec and interpret your requirements differently. Examples from the user’s point of view can never hurt when illustrating something. In fact, why not try using more pictures? Fancy art is open to interpretation; detailed user flows and diagrams function contrarily.
8. What’s not said is just as important as what is.
Going back to the internship shall-should-may guy. Another really great insight he had: Everything that’s not said in the spec is up to interpretation by stakeholders and the rest of the team. That can be a good thing if there are lingering questions that the team aren’t going to be able to get to until week 7. Just work on other things for the first 6 weeks and worry about it when you get there.
However, that can be a bad thing if your team has a long-distance partner and it’s not easy to rectify differences in interpretation. Part of agile development is maximizing the amount of work not needed. Try taking really detailed, technical sections and putting them in separate sections or in a separate document entirely. The latter makes it easier for devs and designers to understand each others’ thought processes, since detailed conversations will be given their own space to develop.
9. How about non-requirements?
Sometimes, it’s easier to define some things your team won’t do before determining what it will do. A non-requirement list could help to take the ideas that pop up and get shot down over and over again in team discussion and lay them to rest. You could also use a section like this for frequently asked questions. When SantaSweaties presents its project and someone inevitably asks if the team’s considered tank tops for all the people in warm climates, the team can definitively say it has, and point to the list. Makes more a more productive presentation, no?
Do you have any other ideas for how we can make feature specs more useful? Feel free to talk to me or leave a comment!
Image Credits:
