How Much Documentation Do You Need?

When you start building your product, there are any number of paths you can take. If you’re a developer or have a technologist on the founding team, you can just start writing code and slapping things together. If you’re following the lean startup method, or the business model canvas, maybe you do a bit of wire-framing and put together a high level list of use cases.

Documentation is for later, right? That’s what big companies do. Not startups.

Well… not so fast.

Over the last six months I’ve been doing a lot of architecture work for a product launch I’ve been working on. Architecture work is a fancy phrase for thinking about how the system should work and then writing those thoughts down to share with others. The company I’ve been working with takes a disciplined approach to building software, and they require a specification before code gets written. I’m not talking about some big, bloated document, but a doc where you capture all of the key components, how they will interact, and how they will solve the problems you need to solve.

But wait. Isn’t part of the “agile” way of doing things where you go, then change direction when you need to, rather than doing a bunch of planning? Why put in a bunch of time ahead of the actual work just thinking about what should be done?

The answer is, as always with me, about wasting time and money. There’s something about having to distill your thoughts to paper and actually map the requirements to your design that exposes tens of flaws and gaps that have not been addressed. Those flaws cost you invaluable time in the course of building a product. You need to strike a healthy balance between going fast and going with purpose and intent.

The other benefit to documenting your approach is that you can then go back to it later and, if you missed something critical, figure out where in the process you missed capturing that detail and adjust your process in the future.

In the next few posts, I’m going to go into detail about how you document the technical specification for your product. I think you’ll find that if you follow this approach, the time you invest up front will save you weeks and months once you actually start development.

We’ll cover:

• Writing use cases
• Using sequence diagrams to illustrate interactions between system components
• Creating a data model
• Creating prototypes / pseudo code to test your designs
• Documenting system components
• Sharing your designs with others / getting feedback
• and more

You’ll get templates and samples along the way to use with your team, and be introduced to some disciplines that the best companies use every day to build successful products.

By the end of this mini-series, you will have what you need to use documentation to actually speed up the development process, not slow it down.