In the first post of this series, Spec’ing the specs: What should my software do?, we took a look at some of the high level considerations that go into planning software projects. In this post we’ll focus in on the online tools and processes that teams can use to capture project requirements.
Why do we need to document requirements at all? There’s no shortage of horror stories out there about the pitfalls of over documentation. You’ve probably seen a phonebook-sized spec document propping open an office door somewhere.
Documentation for the sake of documentation is a waste of time. But clear, concise documentation supports software projects in a few key ways:
- Clearly defined requirements guide your team’s decisions throughout the life of a software project
- Consistently recorded decisions remind your team why you made the choices you did weeks, months, and years from now
- Consciously deciding what your software should do makes it much easier to test that it actually does it once it’s complete
Capturing collaboration
The easiest way to capture the decisions your team makes on a project is to use collaboration tools that do it automatically. There are many tools out there on the web for exchanging ideas and resources. These tools include features for messaging, document sharing, wiki style documentation, task tracking, and so on. These features improve upon disconnected communication channels such as email and phone conversations.
Establishing the use of one of these tools at the very beginning of a project is important. As the project evolves the tool will serve as a switchboard for communication. And later down the line the team can track back to review progress and revisit not just their decisions but the decision making process.
Even more important though is that your team uses a tool consistently. If you notice that people have not been logging into the system or topics pop up in conversation that are not reflected in your collaboration, it may be time to reevaluate your process. You don’t want to impose a system that runs counter to the natural way your team communicates.
Some example collaboration platforms:
- Basecamp
Online project management, collaboration, and task service - Activecollab
Project management and collaboration software package - Sharepoint
Microsoft’s often reviled content management system. Sharepoint has many drawbacks but if you have access to it within your organization it can be a better communication tool than none at all.
Wireframes
Documentation is important. However nothing generates more feedback than giving users something visual. One way to do this early on in a project is to create wireframes. Sometimes called mockups, wireframes are limited functionality visuals that show users what an application will do. Wireframes are much easier to change than a completed and deployed application.
Wireframes range in form from static images to working HTML pages. They often leave out frills like colors and graphics to help users focus on functionality. Wireframes are only a tool. They will not draw out feedback from everyone on their own. The less interactive your wireframes are the less feedback they will draw out. Your team will need to review wireframes as they evolve with users and experts in person to get the most value out of them.
Some example wireframing tools:
- Balsamiq
Software mockup tool for quickly creating static wireframes - Design software
Template sets for iphone apps, web browsers, and so on. - Development tools
Build some basic screens in HTML. Partially functioning screens take more time to create. But they are the most interactive visuals you can give users.
Let the tests tell the story
Behavior Driven Development (BDD) is a development methodology that has been gaining popularity. It encourages developers to collaborate closely with business participants throughout the life of a project.
The approach is often described as outside-in. A team defines very clearly what software should do. Tests are written using testing frameworks that closely resemble plain English. This allows analysts and QA teams to understand the tests and participate more deeply in a project.
As software is created it is held to the results of the tests. The tests ensure stability and quality in a software project as features are added and changed. The tests also serve as a living document of what the software should do.
Some example BDD testing frameworks:
- Java: JBehave
- .NET: NBehave
- Ruby: Cucubumber
In this post we’ve covered some of the interactive forms your software documentation can take. Check back for a later post when we’ll talk about what to do with your roadmap as your team jumps into building software.