Spec’ing the specs series

• What should my software do?
• Rethink the manual
• Keeping a project on track

Hopefully these posts will make you think a little about your own team’s software development process. None of our suggestions are miracle fixes. And most can be tested out separately from the rest. So jump in and give one or two a try. See what works in your organization.

Speak up with your own suggestions and reactions in the comments.

Collaboration has emerged as the common theme for us in designing and developing software. For any plan to have a chance at successful execution, the people charged with building it, the people who will use it, and the people who have expert knowledge about the business behind it need to work together from start to finish.

Collaboration certainly shouldn’t stop once developers start writing code.

Determine features, schedule priorities

During the planning process your team will have defined what the new application should do. The next step is identifying chunks of releasable features. Rolling out useable pieces of your new application over time will encourage your team to exchange feedback while changes are still reasonable.

For example, if you are building a member restricted web application, the first releasable feature would probably be a landing screen restricted by a username and password login. The next logical piece might be a screen to add and edit system users. Almost immediately business experts and end users can begin to interact with the system they helped plan.

Once you have a rough outline of features determine which features take the highest priority and which fall towards the lower end. A schedule of priorities gives everyone a clear idea of what to expect as the project proceeds.

The schedule doesn’t have to include exact delivery dates to work. But staying on top of a rough estimate of delivery dates for features can be very helpful as you have to make priority decisions deeper into a project.

Continuous integration

In order to participate your team members will need access to the project as it evolves. If your project is web based that means having a beta server with the most up to date web site on it. If your project is a desktop app that means having an easily installable and updatable beta application.

Continuous integration is a software development practice that aims to automate merging of features into a single deployable software update regularly. As your developers write code they should be committing it to a source control system. Whenever a feature is ready for beta they can flag it for release. When this happens a continuous integration system automatically assembles a new beta version of the application. Most systems will notify team members when there’s something new to review.

Automating the deployment process removes a process hurdle and makes it much more likely that features will be deployed for review.

Business experts need to see test results

From the very start of your project business experts should be involved with crafting tests. They should also be able to access test results. Your team should use a testing approach that is accessible to technical and nontechnical team members alike.

In our second post we mentioned Behavior Driven Development practices. The frameworks we mentioned (JBehave, NBehave, RSpec, Cucumber) push tests away from techno-speak and towards plain English. This can make it easier for business experts to understand the results of tests written by programmers.

Whatever testing platform you use, get your business experts writing test cases. Having test plans written by business experts is better than leaving testing to programmers alone.

Before you do anything else, start an issue list

Create an issue list at the very start of construction. Make it writable by all team members. As issues or new features come up, enter them on the issue list. Allowing business experts to enter tickets will alleviate some of the interruption that can encroach on developers while ensuring all ideas/issues are captured.

From time to time, everyone should revisit and refine the issue list. As tickets are addressed and released, close them. Look through the list often and look for misplaced items. Recategorize and reprioritize tickets regularly.

Any decent ticket system will allow for notifications. A well used ticket system can serve as a central notification clearing house and historical record for project progress.

Wrapping Up

Once coding starts communication, issue tracking, and testing are the keys to a successful project. Consistent participation from technical and expert team members is the surest way to keep a project on track. More importantly this kind of cooperation will enable your team to adjust to changes because new issues will always come up.

Hopefully this series has given you some ideas on how to improve your team’s process of developing software. None of our suggestions are miracle fixes. And most can be tested out separately from the rest. So jump in and give one or two a try. See what works in your organization.

Anything you can do to foster an environment of collaboration will increase the quality of your end product.

In the old days, reporting was a tedious process, and from the business perspective, appeared to take forever.  Here’s a likely scenario:  you think of a report you need, you write-up your report request, send it to the IT dungeon, and in 2-3 weeks you are informed it is available from menu “X” in system “Y”. You get excited, login, only to find the layout wrong or groupings off. You start the request process all over again (fun times!).

With a BI tool at your users fingertips, they can sort, group, heatmap, piechart, export, and print to their hearts content. Never having to request another report from IT again (well, almost never). BI tools increase productivity and add efficiencies to an organization. There is one caveat. You organization must be ready for BI. If your user base is not able (through lack of training) or not willing (fears change, afraid of technology or are just plain lazy) to use your shiny new BI solution, your investment was wasted. Be sure to get your people on-board and excited about BI and what it can mean for them before you make a purchase.

I recently implemented a BI solution for mid-sized client and thought I would share some of the things I think should be included in every BI offering. Most of the items I will mention are provided by the major vendors such as;

• SAP/Business Object’s Web Intelligence Studio
• LogiXML’s Ad-hoc
• Microstrategy BI
• IBM’s Congnos
• Oracle’s OBIEE Plus
• Microsoft’s SQL 2008

The list below outlines items I feel are critical in a BI package.  It is by no means all-inclusive.

Most, not all, of the BI offerings I mentioned at the beginning of this post have the features I listed above (some more quirky than others). Each organizations needs are unique, so in the end you will need to marry features to your specific requirements. However, I have found that the items above are core to most business needs.  Take your time and test-drive each product on your potential buy list.  You will be glad you did.  Happy BI Hunting.

One way to strike that balance is to encourage team members to communicate on their own schedule. In person visits, phone calls, and instant messaging are great tools. But they require immediate attention and can derail a person’s attention. An alternative is to use disconnected communication tools.

Provide an internal blog, a short message Twitter clone site, or an IRC style chat room and give accounts to everyone. Whenever someone hits a wall or completes a task, they can post a short message. The running list of messages will be available whenever other team members check in on it. Everyone keeps up with what’s going on without the pain of time draining meetings. You also get the added benefit of connecting folks who work in disconnected offices.

Meetings don’t have to be time draining. Short, focused meetings can be very useful. Just make sure every meeting has a clearly defined purpose. Get in the habit of sending out agenda points. Keep the agenda points limited to decisions points or group related updates.

Encourage team members to discuss and refine the points ahead of time using your collaboration tools. Don’t schedule an hour unless you really need it. More often than not 15 – 30 minutes gets the job done.

Whenever your team is gathered you’re spending as many worker hours as there are team members. Hash out as much as possible upfront to make sure the time spent together is worth the cost.

What other forms of communication do you find work well for you? Leave us some ideas in the comments.

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.

There are many reasons (just google it) why software projects fail: lack of direction, poor specs, an inexperienced development team, lack of any real testing and the list goes on.   Any of those issues can sink the proverbial development ship.  However, the issues I listed are merely the symptoms of a much larger disease.  In fact, many of them will cease to exists if you incorporate a simple principle into how projects “get done”.   That guiding principle is “partnership”. Partnership?  Yes, partnership. Sounds simple and even over-used, but it’s foundational to the success of just about any team effort.

In a “true” partnership” each party knows what is expected of them.  They each know the role they are supposed to play and realistic expectations have been established.  Unfortunately, most development efforts never address the importance of business and IT partnering for a common objective.  Instead, the coders code and the business people wonder why they don’t see screens yet.  This doesn’t happen everywhere, but it’s all too common.

So before you start that next project, set aside time to discuss how the “partnership” will work.  Listen and learn about the implied vs. explicit expectations of your partner.   For example, in my experience, there are two common implied expectations that seem to exists on any project:  1) the business will always expect to receive a reliable and testable application and 2) IT will always expect the business to provide clear specs and personnel to conduct meaningful testing.  Understanding and meeting those two expectations will go a long way to helping you achieve success, but each partnership is different and comes with its on set of rules, so be prepared to adapt.

To often, “partnering” is referred to as boiler-plate lip service or just another over used business cliche’. The truth however, is that no project can succeed without it.

I have been on facebook for while now, but mostly to reconnect with old friends and lost family.  Twitter on the hand, was relatively foreign to me.  Tweets?   What is that?   Thankfully though, a colleague of mine pushed me to start looking at Twitter.   Not only for the social connections but also for the educational aspect (I will get back to this one) and the ability to talk about, I mean tweet about, my organization and how we can help others.

I have to say, I was reluctant at first.  Talk about information overload.   However, once you learn to cull and search and follow your own interests, an amazing world starts to open up.   I mentioned Twitter and education.  I am amazed at how twitter has enhanced my knowledge, especially around areas of personal interest.   Twitter in some ways (for me at least) is like a living encyclopedia that is grows each day.  Granted, there is some junk out there, but being able to tweet with people around the world about common interests and get their perspective on topics and current trends is simply amazing.

The more I learned about twitter and social networking, the more I was on the fence about “promoting” our business via social channels.  Part of me felt as if the social networking world was meant for you and me and not business.  After all, I really don’t want to login to twitter and see Pepsi ads.   My business half realized the opportunity social media offered, but I wanted to strike a balance.  I have always promoted my company as being real people helping others succeed, not some corporate monster trying to take over the world.  So, I decided that any discussions about my organization via social media would have to meet that same standard. No brash used-car sales promotions or ALL CAPS TWEETS!   Its important to me that we connect with people and if that leads to business great, but making friends can be even more rewarding.

As we continue diving deeper and deeper into the Twitter pool, I hope to post new aritcles updating everyone on our experiences and what we have learned along the way.

A clearly defined road map for what software should do will help make the most of everyone’s time and efforts over the lifetime of a project. The tricky part is crafting the right road map for your project.

Documentation is the old standby. Does anybody read it? Meetings can be helpful. Do the hours spent really improve the product? Prototypes look like rapid progress. Are the subject experts able to make any sense of mockups?

This post is the first in a series on how development teams can better collaborate with their business counterparts to capture what software should do. This first post focuses on why road maps are so important. Another will dive deeper into different approaches for capturing requirements in a meaningful way. And a later post will look at taking that leap from a road map into construction.

Making something out of nothing

A blank page can be a frightening prospect. Even when a team is upgrading an existing application, it can be intimidating to define what screens and what features are needed to launch.

At the very beginning of the requirements gathering process it’s best not to think about software at all. Instead, the focus should be on what users need to accomplish. Project members should spend time mapping out the goals and habits of the people who will use the new software.

If a team is developing an application for a company then they can spend time observing the day to day tasks of the people who work there. If they’re developing a product for the web then they should spend time talking with people likely to use the application. They should find out what tasks people are doing now in some other way. It’s a good idea to ask these future users what tools they think would improve their lives.

It sounds like a simple thing. But listening to users is a step that we often skip. It should always be our first step.

Communicate, rinse, repeat

Often the developers writing software aren’t experts in the subject matter behind a project. Software teams rely heavily on point people with business knowledge to help them build useful tools. It’s important that developers establish a collaborative relationship with the subject experts from the very beginning.

There will always be a period of requirements gathering at the beginning of a project. Collaboration shouldn’t end once developers start writing code. Business point people need to remain engaged with the development team throughout the life of a project. Keeping them connected as the project progresses is the best way to ensure the project remains true to the road map.

When subject experts and developers collaborate the road map becomes a living document. The teams’ working relationship will make it easier to make adjustments as issues arise. This will save on many headaches on the way to launch time.

Capturing the magic

Ideas can be magical. But putting ideas into action is where the real magic happens. And putting ideas into action will be much easier if everyone agrees on what software should do up front.

That still leaves the question of how to go about capturing those requirements. It’s not enough to jot down some ideas and move on to coding. It’s important to think about how the requirements will be used throughout the life cycle of the project. The content is fresh in everyone’s head when they start. Three months from now they’ll have to refer back to those notes. Will they still make sense?

Ideally a team should use tools that allow everyone: developers, subject experts, managers, and maybe even some users, to have a window into the project as it evolves. Nothing communicates the progress of a project better than tracking work as it moves along for all to see. Online tools such as wiki’s and other collaboration services can become a natural part of both the requirements and the development processes.

In the next post of this series we’ll take a closer look at some of the online tools and processes that your team can use to capture project requirements.

A development methodology is the core of a good software process.  However, there are no one-size-fits-all methodologies. While each “system” (waterfall, agile, etc) has its own merits, there is no silver-bullet solution that will fix your development process (or lack thereof). A methodology is just one link in the chain of a solid process. It’s important to look at the different methodologies available and adopt (and adapt) the one closest to you end-goal.

So what else do you need to make a process really work, here is a short list:

Methodology

Every good process needs to starts with a solid foundation. Even if you adopt you own form of a methodology, which is what most of do in reality, it is good to start by picking an existing one with a good track record. When picking a methodology, remember to consider where you want to be as development team vs. where you are today. I know that might seem simple, but I have seem many groups pick a method that closely resembles who they are vs. who they want to be. Again, it’s human nature to take the path of least resistance. Another recommendation: don’t pick an overly complicated or document-heavy methodology. You’ll notice I didn’t say document-free. You want to be productive, not mired in documentation.

Bottom line: Pick a methodology that is proven and includes the ideals of where you want to go as a team.

Management buy-in

I know, you are probably saying, “if I had a dime for each time I heard that one”, but this is one is critical. Without real support (i.e.: accountability for those who don’t align with the new process), the process will never take hold. People will not change if there is no consequence linked to NOT changing. It’s just basic human nature.

Bottom line: Wishy-washy leadership = no change.

Team buy-in

This does not mean everyone. You will almost always have the naysayers who like things as-is or want waterfall over agile or vice-versa. I recommend including your most trusted developers, the good ones, in the decision making process as you move to make changes. Defining “good” is outside the scope of this post but lets just say good doesn’t always mean the person who gets things done the fastest. This will help them to see you are committed to them and value their input.

Bottom line: Be inclusive but stay committed to the end result. Understand that some folks may leave because of the change. Be ready for that reality.

Document and Educate

Hey, I’m a developer, what’s with all the documentation? Documenting the process is important to ensure it is repeatable. Keep it simple. A wiki write-up or a simple, yet clear bulleted manifesto will suffice. Do not write a 200 page process document…unless you want it just collect dust. Make the process document available on your intranet to everyone can see it and be prepared to change it when necessary. Meet with your team and explain the points of the new process. Go over why you believe it is better than what you are doing today.

Bottom line: Keep the document simple and clear. Educate the team and make sure they know why the change is being made. People like to know why something is happening, not just that it’s happening.

Review

After each project, conduct a “post-mortem” to determine what went wrong and what went right. This will help to determine if changes are in order. Is your team more effective with this new process in place? Without these reviews, your process will never take advantage of lessons learned.

Bottom line: Be flexible. Always look to refine and improve.

A good process will yield good results consistently. But implementing a process or changing an existing one can be a painful experience for some organizations. My experience has shown that organizations that ignore the failings of their current processes, create an ever-growing amount of “tech debt.” That debt can become so heavy they collapse under the weight.  If you keep your processes simple and flexible, it can change with your organization and evolving technologies, enabling your team to be more responsive and efficient.

Take some time this week to review your software processes. Create a short list of items you know can be improved upon. You will be happy you did it.

No project is perfect. Trade-offs have to be made. Unplanned issues begin to seep in. Communication breaks down. It’s easy to lose sight of the common goal of building a great house. But that’s why it’s essential to have a solid project process in place on every project. The project process is the best way to keep everyone connected and collaborating.

After the house is standing and the clients have moved in, then it’s time to hone your process with the lessons learned on the project. Your future projects can benefit from the things that worked and avoid the pitfalls in the things that didn’t work.

At Bayside we put a lot of thought and practice into our process. We’ll try to use this blog as an outlet for our own ongoing learning process. Hopefully we can start some interesting conversations along the way.