Exploration Phase

The Sample Application: An Online Timesheet System

As I mentioned in the previous chapter, this book tries to follow a flow similar to how a real-world project might flow. In this book, we will pretend that we have a requirement from an internal group (a fictional customer) and use this requirement to build a sample application named Time Expression.

I considered several types of applications to use as an example in this book; in the end I settled on a rudimentary timesheet system because I believed that it was an application most readers would be able to relate to. For example, you might be an employee or consultant who works by the hour, and you submit your timesheet online (and also get it approved online, and so on).

Our sample application, Time Expression, will have a user interface (UI) as well as some background processing. The UI will be web based and will contain screens that provide the capability to enter hours worked, approve timesheets, run management reports, and more. The background processing will include a weekly (scheduled) batch job that is automatically run to send out a reminder email.

Business Requirements

I mentioned earlier that our fictional customer requires a simple online time entry and approval system. Let's go into a bit more detail here.

It is always a good idea to define what business problem is being solved, whom it is being solved for, and why our solution is important to the customer. In addition, it is important to understand what the customer's expectations are: for example, when is the solution needed, and what is the project scope.

Let's assume that a fictional organization wants to build a timesheet system to manage its hourly staff. To get things started, we can define the problem statement as follows.

Given our general problem statement, we can break this down into the following feature set or business requirements; this process could be considered a part of use case analysis, in the Unified Modeling Language (UML) world:

• Hourly employees should be able to sign in to a web application (once or more each week) and enter their hours for each day of a given week. Along with the hours, the employee must select which department the hours are being billed to.

• Employees will be required to submit their timesheets each week.

• An employee's manager is notified of successfully submitted timesheets. The manager must then approve or disapprove the timesheets.

• After a timesheet is approved or disapproved, a notification is sent back to the employee indicating the updated status of the timesheet. If the timesheet is approved, an email is also sent to the accounting department to process the paycheck for the given employee.

• All users of Time Expression will have one or more relevant reports available to them.

• A weekly reminder email will be sent out to employees who have not submitted their timesheets. Another reminder email is sent to managers who have employee timesheets pending approval.

Now that we have some basic business requirements, we can proceed with our software development process.

Software Development Methodology

Every project, small or large, should have some basic structure or process (methodology) it must follow. This could be a simple one-page checklist or a slightly more formal process. Having no process at all is bad, but too much is equally bad. Finding the right balance depends on the customer's needs and the project size, but in summary, I lean toward having less process with minimal (and "good enough") documentation requirements, rather than having a bloated process that can bog down the customer and developers in paperwork and procedures. In this chapter, I'll provide a basic software development process based on XP and AMDD.

Overview of XP and AMDD

XP and AMDD provide some fundamental guidelines for building software applications effectively and rapidly. XP and AMDD are complementary methods because XP provides a disciplined, full life cycle software development approach that stresses customer satisfaction. AMDD, on the other hand, generally provides effective practices for modeling and documentation, but goes a lot further by providing a wealth of additional best practices that can be tailored to each software development project.
 

The Exploration Phase (Beck, 2000) typically involves a combination of exploratory activities that help you better understand the customer's needs and subsequently how the resulting application will be designed and built. The following are some examples of activities that might take place in this phase of the project.

• Domain model A domain model helps to define major business concepts (entities) and the relationships among them.

• User interface prototypes and storyboard These are initial screen mockups to get a feel for how the customer visualizes the application. The storyboard is the flow of the screens.

• User stories A few user stories get the project started and make up the first release or version of the application. User stories (similar to shall statements in other methods) are written by the customer in a brief sentence or two explaining what the customer wants the application to do. Note that the number of user stories you gather up front will depend on the project, but you should have enough to make a good and useful release.

• Scope definition It is important to define the scope of the project up front so that you know what needs to be developed and what can be deferred. It also clarifies the customer's expectations.

• Analysis : This can include a combination of whiteboarding, an informal architectural diagram, a glossary, and more.

Planning Phase
 

Planning can mean different things to different people. For me, it should at least include the following:

• Release plan This is essentially a plan for the next release (version) of a system and can easily be put together using a spreadsheet program or even a word processing program and/or HTML table. It lists all the user stories that will be included in the next release of the system, grouped together in several iterations. Releases are typically of fixed length, anywhere between one to three months; two months is typically an optimal size.

• Iteration plan An iteration plan is developed prior to each iteration. It includes the user stories the customer wants implemented in the next iteration. Iterations are typically of fixed length, anywhere between one to three weeks; two weeks is typically an optimal size.

• Define standards (code, database, process) Before beginning any development, it is a good idea to standardize such things as coding conventions, database naming conventions, processes (build, integrate, deploy), and more.

Iterations to Release Phase (Building Software in Increments)

Iterative development is a term you are probably familiar with. However, understanding of iterative development and what each iteration should include varies from person to person and from methodology to methodology.

For me, iterative development means that each iteration includes design, coding, user acceptance, and deployment of "production ready" code. This code can be deployed to the production environment or, if you are in a large corporation and deploying to production frequently is not practical, perhaps deploying to the acceptance environment will do, so long as it is accepted by the customer, thus allowing you to move on to the next iteration. To summarize, each iteration might include the following activities:

• Development tasks, estimates by developers, and a plan for the next iteration.

• Ad hoc Q & A between developers and the customer.

• Design CRC cards, UML diagrams, and so on.

• Code test first, refactor code/database/architecture as required, optimize later.

• User acceptance testing (UAT).

• Deploy iteration to production (or UAT); this step is also referred to as a small release.

By delivering iterations in this fashion, you can incrementally build the next release of an application. For example, we might estimate three months for a given project and break it down into two-week iterations, resulting in approximately six iterations.

The bottom line at the end of each iteration is that the project should be deliverable; in other words, the small releases should contain production-ready (stable) code, even it provides only a subset of the complete system.

Scope of Project

The scope of project can be defined in many formats. Sometimes it is as simple as a oneto two-line paragraph described by the customer, or it can be more structured using diagrams. Many organizations go one step further and sign service level agreements (SLAs) with the development team. Also, functional and nonfunctional requirements discussions can also occur to help define the scope.

In the past, I have used a table to show what is included in the scope and what is deferred (or excluded) from scope, as demonstrated in Table 2.1, a sample scope table for Time Expression.

 

Maintenance

This is where the application enters a maintenance state. This phase might include training for the user, minor enhancements/fixes (in the form of user stories), as needed. Or the customer might want to do another major release, in which case you would start back from the Exploration Phase mentioned earlier in this chapter.

Applying XP and AMDD to Our Sample Application

Now that we have looked at some background on a generic software development process, let's apply parts of this to our sample application.

Domain Model

Let's start our domain model, which essentially has all the data entities and their relationships, but no attributes. This helps to define some initial domain concepts and their relationships to each other. The domain model is typically sketched while working with domain experts and people with business knowledge, such as business users and analysts.

Figure 2.2 shows the domain model for our application, Time Expression. As you can see, our domain model has a simple design because it contains the bare-minimum number of entities to get us going while following a clean design. Again, we just need a simple domain model to start with, something good enough for us to move forward with, which we have now.

User Interface (UI) Prototype

Now that we have a fairly good idea of the features our customer is looking for in Time Expression, we can rapidly mock up some prototype screens to allow the customer to test drive the mocked web application.

By developing prototype screens early on, you put a face to the application, which gets people excited and motivated to get the application built. This is also a good way to eliminate many of the cosmetic changes up front (such as fonts, colors) and come up with an agreed upon consistent look and feel that can be implemented using cascading style sheets (CSS). Furthermore, you can use prototypes to model the business process and subsequently use the same prototypes to define the users' stories (covered later in this chapter).

Figures 2.3 through 2.10 show what the various screens in the Time Expression application will look like. We will begin designing this application in the next chapter; then, in subsequent chapters, we will get our environment set up and begin developing some code!

At this point, let's keep these screens as simple HTML (versus JSP) files so that we can pull them up locally in a browser instead of having to run them in a Java web server or pull them up in a JSP/HTML editor each time. When working with a customer, it is a good idea to keep technology out of the picture, as much as possible, until you are ready for developmentthis keeps things simple, so you can avoid any "technical difficulties" and instead focus on the business requirements at hand.

User Stories

Given the business requirements and UI prototypes defined for Time Expression earlier in this chapter, we can now define a set of user stories for our application. As explained earlier in this book, I decided to use XP/AMDD; therefore, you see the use of the term user story versus use case. Although these serve similar purposes, user stories tend to be shorter than use casesfor example, one to three sentences each. The remaining details can be discussed between the developer and the customer when the developer begins working on a given user story in the planned iteration; hence, the term active stakeholder participation.

Use cases come in many formats themselves. The three I'm familiar with are formal, brief, and casual. The casual format is probably closest to a user story because it is short and informal. Formal use cases can entail a page or two of requirements with preconditions, postconditions, success/basic path, failure/alternative path, and other sections for each use case. The reason I have described use case and their formats here is because certain organizations define essential use cases (or even business requirements with "shall" statements) first, and then later break each use case down into one or more (maybe even several) user stories using our guideline of one- to three-day development per user story or development task.

We will use user stories in this book to not only define the requirements, but also to name our Java classes, using the story name/tag, and create acceptance tests. Table 2.2 shows the user stories with the priority and initial estimate to complete. Note that the user stories you might find in the real world might be a bit more detailed than what I have shown in Table 2.2; however, given the simplicity of Time Expression, these work fine for us.

Incidentally, a good book to check out on user stories is Mike Cohn's User Stories Applied: For Agile Software Development (Addison-Wesley Signature Series, 2004).

The estimates shown in Table 2.2 are initial estimates, or sizing. The developer provides more accurate estimates at the beginning of the iteration when the user story will be developed, because the user story can be broken down into development tasks to better size the time required to complete the entire user story. Incidentally, I have come across real-world projects where they did not do the breaking down of user stories into tasks, nor did they size the user stories during iteration planning. The reason for this was because sometimes the user story priorities changed or the user story itself changed, so the upfront work was for nothing. Instead, they picked two to three stories on day one of a new iteration and only estimated those.

Points (last column of Table 2.2) are some unit of measure relative to the given project. For example, 1 point could equal 1 regular workday, 1 ideal workday, 1 week or another periodwhatever the customer and developers agree on. Whatever each point might measure is then used to provide estimates to the customer.

Ideal (development) days are a good way to estimate projects because it factors in planned and unplanned events (for example, meetings, computer problems, sick leave, and so on). The difference between a regular day and an ideal day is referred to as the load factor.

A load factor, typically between 2 and 4, is a number you multiply your initial estimate by to come up with an ideal day. For example, I like to use a load factor of 3 for projects where I have a good understanding of the business requirements and technologies. (Note: If you believe there are risks involved, such as a learning curve related to a new technology, you can use a higher number, such as 4 or even 5.) For example, if we know a development task will take me approximately 8 hours of uninterrupted, totally focused, heads-down time, we can multiply that by 3 (that is, 8 * 3) and come up with 24 ideal hours or 3 ideal days (assuming a 8-hour work day).

In this book, we will develop the Enter Hours and Timesheet List (items 1 and 2 in Table 2.2; both with priority 1). So, if we use these two screens as example, it would take 9 actual days to complete these screens (that is, 3 ideal days times the load factor of 3).

Release (and Iteration) Plan

After the customer (end user and/or business analyst) has defined the user stories, the customer and development project manager (and/or developer) can put together a release plan for the next release or version of the application.

A release plan is essentially a project plan listing various system releases and the dates for each release. In this book, we will assume that we have only one releasefor example, v1.0.

Releases are typically small, about 1 to 3 months in length. Each release consists of a set of user stories the customer wants implemented in that release. Each release is then further broken down into iterations.

Iterations range between 1 to 3 weeks in length. Each iteration contains a list of user stories chosen from the set of user stories for the given release that the customer wants implemented in that iteration (along with defect fixes from previously failed acceptance tests).

Based on the user stories we defined earlier in this chapter, we can come up with an initial release plan, shown in Table 2.3, to incrementally build release v1.0 of our application.

Our release plan does not use priority 5 user stories because these will be pushed off to release 2 of our application. Of course, this is all fictional and many of the examples we have looked at so far, such as the iteration and release plans, are for demonstration purposes only. In the real world, you are bound to see more detailed plans.

After the release plan containing the various iterations is defined for the next release of the software, the developer can begin working on the first iteration.

Prior to each iteration, the customer and development staff get together for an iteration-planning meeting, the outcome of which is an iteration plan for the next iteration. The customer picks the user stories that will be developed in the next iteration. The developers break down each user story into individual development tasks required to implement the user story. This is done so that each development task can be assigned to a developer, but more importantly, the tasks can be used to more accurately estimate the total development effort for the given user story and, in turn, the next iteration.

If the total estimate or points (to implement all chosen user stories for the next iteration) exceeds the total points implemented in the previous iteration (known as the Project Velocity in Extreme Programming), the customer must choose which user stories (or defect fixes) to defer to a future iteration or release. If the opposite is truethat is, there is room to get more done in the next iteration, the customer may add additional user stories, defect fixes, or enhancements, if needed.

For our purposes in this book, I have skipped including a sample iteration plan because this book is more about development than process. Also, formats of an iteration (and release) plan can vary, so instead I chose to leverage the release plan (see Table 2.3) and group our user stories by priority in it instead of breaking them down individually in each iteration plan.

Glossary

This is probably a good time for us to define a glossary for Time Expression.

A glossary is essentially a set of common terms, or project vocabulary, that everyone agrees on for the project. This list can include business terms (for example, Timesheet and Approved) or technical terms (for example, Entity, used while discussing the logical data model). The obvious benefit of a glossary is that it gets everyone in agreement with the terminology and definitions of each term to avoid any confusion. (We have enough of that already given the terminology/acronym madness that exists in our industry.)

• Accounting The accounting department/staff.

• Approved Status of a timesheet when a Manager approves a previously submitted timesheet.

• Employee A person who works on an hourly basis and reports to a manager.

• Executive An officer of the company, such as CEO, CFO, or COO.

• Hour A full hour of billable work that can be entered into a timesheet and the employee can get paid for.

• Manager Direct supervisor of an employee.

• Paid Status of a timesheet when the accounting department has issued a check.

• Period Ending Date This is the last day of each week (Sunday, in our case).

• Pending Status of a timesheet until the user submits it.

• Submitted Status of a timesheet when an employee has submitted a timesheet. Timesheet is "locked" from further changes by employee.

• Week A 40-hour workweek from Monday through Friday.

Whiteboard Architecture

By now, we have enough information to put together an informal architecture diagram. Figure 2.12 shows a high-level architecture diagram for Time Expression (on an indispensable tool of the trade, the whiteboard). By establishing this diagram, the developers and customer can agree on major technologies (for example, Java, database, web/app server) that will be used to build Time Expression.

We will use an electronic and more detailed version of this architecture diagram in the next chapter to help us go one level deeper into the design of the applications. Converting whiteboard diagrams or CRC cards to electronic formats are my personal preference because legibility isn't a real concern with electronic artifacts. However, you could simply digitize artifacts such as whiteboard drawings and CRC cards via tools such as a digital camera and scanner, respectively.

Although I have some fundamental practices I use on all projects, I typically pick and choose what applies to each project and customize the software development process based on the needs of that project and customer. For example, in our sample project/application in this book, Time Expression, I have used several of the techniques described next and shown in Figure 2.1 (refer to agilemodeling.com/essays/agileModelingXPLifecycle.htm for details). Note that although I have adopted the XP and AMDD way, there might be a few spots where I customize these methods (Project kick-off, for example) to accommodate what we need for Time Expression.