November 2nd, 2017 / Nicholas Elliott

Whether you realize or not, if you develop software then you have created a Functional Specification. If you don't know what that is, far better writers than I have covered it in detail, but to quote Joel Spolsky:

"A functional specification describes how a product will work entirely from the user’s perspective. It doesn’t care how the thing is implemented. It talks about features. It specifies screens, menus, dialogs, and so on."

This is the 1000 page spec document for the first flashlight app. True story.

The exact ins and outs of your particular process may differ, and what works for one person may not work for a development studio. It doesn't matter if you are writing a 100-page detailed document, an off-the-cuff slack conversation with a friend, or a thought that never leaves the confines of your (assuredly brilliant) mind. Something decides how that software should works. At that point, it's just a question of how useful your process is, and how much work it takes to create it.

On its surface, ‘Agile’ development processes seem to throw out the old way of rigorous planning of phases and comprehensive documentation, in favor of standing conversations and objective-focused design. I thought it worth discussing what a functional spec looks like in this environment; or, indeed, if it is needed at all.

"If you do not know where you come from, then you don't know where you are, and if you don't know where you are, then you don't know where you're going. And if you don't know where you're going, you're probably going wrong." -- Terry Pratchett

In the Good Old Days (when the floppy disk icon on the ‘Save’ command was literally true) software was developed according to the Waterfall Principle, and that was The Way. Waterfall design consists of planning everything in meticulous detail in advance; creating hundreds of pages of documentation; getting dozens of signatures to ‘sign off’ on the design; developers creating their component of the software in harmonious concurrency; then reaching a month from release, realizing that nothing works and you could never even realistically create what you thought you had designed. Waterfall has no flexibility to meet the challenges of a shifting development environment - and if reality doesn’t match your plans, reality wins every time.

This guy thinks he has it bad but he’s never had to explain why he still can’t ship his product.

In those days, the Functional Spec was king. It detailed everything that could ever happen (except for all the things you didn’t think of) and how to handle every situation that came up (except for the things you forgot). Deviating from the Functional Spec was a Big Deal, and required a giant Change Request that could rival the original spec document for complexity. The good thing about having a spec was its ability to enforce consistency and a grand vision -- all developers could look at that one document and know that everything they were creating was building towards the One True Vision.

These days, development studios tend to use a more flexible style of development. Instead of front-loading all of the design knowing that it’ll miss the mark anyway, we revise and readjust in small increments along the way, only planning in precise detail the work we’re about to do. The Agile Manifesto asks developers to value:

  • Individuals and interactions over processes and tools
  • Working software over comprehensive documentation
  • Customer collaboration over contract negotiation
  • Responding to change over following a plan

Agile Development is very objective-based, and can provide a lot of velocity for objective-based development. That is to say, a piece of software is broken into ‘User Stories’ such as:

"As a clown, I want to be able to calculate how many other clowns will fit in my car so that I can impress the crowd with the MOST CLOWNS"

"As a ringmaster, I want to be able to calculate the gas mileage of a car filled with clowns so I don’t go broke letting those stupid clowns show off"

This is basically what all clowns look like in my head.

Great! Now we can design some software that does those calculations, knowing that what we are doing is incredibly valuable to the end user, and close the User Story as completed. This creates very useful software for that specific goal, but over time (as the complexity of an application increases) it becomes harder and harder to track the impact on the entire application. Your design is tracked in a dozen user stories (ideally written on a single post-it note). Is the next user story consistent with all the ones that came before it? Better hope someone on your team has a really good memory, because a couple of months ago you completed a user story letting tigers calculate the maximum velocity of a mini cooper filled with clowns, and something tells me you’ve got a conflict of interests here...

I was going to use this to represent the fragility of focusing on a single block at a time,
but now I’m just mad because this kid is clearly way better at Jenga than I am.

Keeping the design philosophy of an application coherent, while assessing the myriad impacts the smallest change can have on every other feature, and yet still allowing the flexibility to choose the better path when you inevitably discover; a superhuman task at best. It’s no surprise that they have been treated as mutually exclusive goals.

Here at (brace yourself, inevitable self-plug incoming) Skyward we’ve adopted a few practices that have proven themselves useful. These are our tenants:

  • Provide high-level unifying vision, without specifying details that are hard to adjust.
  • Explore the complexity of interactions, without planning beyond your immediate goals.
  • Inform those who will come after you, without tying yourself into obsolescence.

Granted, they may sound a lot like telling someone who is about to walk a tightrope "Just walk in the middle!" but there’s an advantage to having this discussion now.

The Functional Spec is dead. Long live the Functional Spec!

I have a friend that is very fond of reminding me of something anytime he’s impressed with humanity:

"We live in the future!" -- A good guy

The printed-on-paper documents of yore have been replaced by crowd-edited wikis and smartphone-digital-signatures. You can track the impact of your code through thousands of tests running on your continuous integration server. You can (and I just googled this, so it’s definitely true) just ask Siri to design your app for you. Okay, maybe not that last one (yet!).

The point is this: you can have fantastic, overarching documentation and still have an agile, responsive development process. The once impossible task of maintaining a cohesive vision yet remaining responsive to changing needs has been made practical with the advent of new technologies. Your Functional Spec can draw from your workflows, or push out to them with a hundred pieces of communication and software development tools - everything from Slack to Jira to Trello - and virtually assemble itself

The problems of Waterfall’s methodical and rigorous process aren’t entirely gone, but can be mitigated with good tools and a smart process. You can have your cake, and eat it too.

The cake is NOT a lie.[1]

Now that we’re all convinced we can do it, and are pumped up and ready to get it working, come back next week for Part 2 where I explain how we address those issues and use the process successfully.

[1] Give me a break, I have kids and haven’t played a game since 2007