Thursday, June 25, 2009

TimeTrak: The Requirements

This web application will be very simple. My goals lean more towards using the technologies of interest, namely, Google Web Toolkit + Spring MVC + Hibernate. Nonetheless, every project must start with a set of requirements.

Timetrak will be a multiuser application targeted at independent contractors that regularly participate in others' projects and desire to keep track of their tasks and hours spent doing project work. I'm one such software developer.

The application will support the following roles: an administrator, project supervisors, developers, and clients.
The administrator is charged with creating and managing user accounts, and resolving access/rights issues.
The project supervisor creates projects and assigns developers to the projects' tasks. He also sets the various hourly rates or contract terms for the project, and is responsible for inviting the project's client to participate. Supervisors also approve invoices posted by developers, at which point they are visible to clients.
The developer performs actions according to the tasks assigned to him, keeping track of hours worked. A developer can create new tasks in the projects he has access to (which will automatically be assigned to him). At any time, a developer can generate a bill for a particular project on completed tasks.
The client can review projects and see progress reports. Project details (such as task activity and which developer did what) are hidden from him. The client can review and pay invoices online, posted by managers.

Whenever a task gets some action, a daily email is sent to the client detailing what was done, and how long it took. If the client has multiple projects, only one email will be sent.
When a task is included on an invoice (billed), it cannot be modified. It can never be modified again after the invoice is paid, but can be activated again if the invoice is cancelled for whatever reason.
Tasks will have status that depict which development stages they are at: ready (not assigned to a developer), assigned (no actions done on task), in progress (some actions posted), and completed. Only completed tasks are billable.

I'm sure there are a lot more requirements that could be discussed, but the above are the crux of the project. It's cumbersome to try to adapt traditional SRS documents for a web application, and Agile methodologies will not provide the kind of documentation needed for a typical SRS, so the best strategy is to marry the two. I use a stripped down IEEE-recommended SRS with all kinds of web-specific sections depending on the project.

Write SRS's to focus on what the application will do only, who is involved, and the definition of the various entities you mention (for the benefit of the database developer). From this one document, system designers should have no questions about what to do. Even for web environments, you want to avoid discussing technologies in the requirements doc, unless the customer requires it (the document should be technology- and language- agnostic = a design or implementation decision). For this application, my SRS is only 11 pages long front-to-back - that's how simple it should be.
Typically, solicitation of information and clearing up ambiguities, and finally writing the document takes 2-3 days, depending on how quickly people are responding to emails or returning calls, or how often requirements meetings are held.
Requirements gathering is a billable activity: a lot of clients assume that you do it for free. I think that as long as they can use the specific information and your interpretation of their needs to develop a product, you should be paid for it. You may choose to charge a different rate - this activity is typically done by a consultant.

Sunday, June 21, 2009

TimeTrak: How To Start A Project

Before you write the first line of code for any project, you better have a plan! Better still, you should have full documentation for the project, including requirements documents, design documents, and most importantly a contract that defines the project scope. To me, defining a project scope includes finalizing how you will be paid, how much, what you will do, what the project encompasses, and perhaps a schedule that's subject to change. How do you get there?

I usually start by understanding the project scope. Through emails and coffee shop meetings, I seek to understand what the product from the project is expected to acheive (the goals) from a non-technical perspective. Usually, it is business-minded people you will encounter first, and most are good at expressing their ideas and what they want. Take good notes because it's your job to translate all their blurb into something that makes sense technically. The results of this analysis will tell you whether (a) you have the skills and resources for the project (b) what is involved so you can adjust your price, or (c) whether the project can be successful at all. This has to last a short period because you are doing it for free.

Next you draw up a requirements document that explains what you understand and how you intend to acheive the solution/product. I use a modified IEEE-recommended software requirements specification (SRS) template, providing an overview of the project, breakdown of the project into phases, cost analysis, and a contract. Before you start the first phase, this has to be agreed to by all parties, because it locks down the scope.

As soon as the project spec is agreed to, you may now start paid work. I usually prepare by setting up my development enviroment (laptop, libraries I'll need, tools - including IDEs and analysis and test tools, test bays, and brand new notes book). The first day is spent testing a development process I'll use: I prefer end-to-end agile-like development of features including requirements analysis, design, implementation, and test/integration. You build documentation as you go along. The foundation infrastructure in place, you are ready for the first phase.

Thursday, June 18, 2009

TimeTrak: GWT+Spring+Hibernate = Awesome

I'm starting a new series about developing interactive web applications using the Google Web Toolkit (GWT), Spring MVC, and the Hibernate persistence libraries. When I started researching these technologies, I could not find adequate and straighforward information about this combination: at best, books I considered from local bookstores were outdated by 2 years or more!
So I've been digging around on my own, looking at forums, and figuring out things myself.

The series will consider all issues involved in developing a web application the way I do it, which may be different from best practices and other industry standards. This is simply how it works for me currently. The goal is to share knowledge and lessons learned. I am still learning these technologies myself, but I know this information will be useful to someone out there just getting started.

You will need: pretty good Java programming skills, good web design skills (for the presentation layer, that is, HTML/CSS), a mind of a software developer (to design applications and how the various components interact), an understanding of relational database concepts (especially object-oriented models - ORM), and good IDE (I use Eclipse a lot, but I'll write the segments for using NetBeans for the benefit of their documentation project), and lots of time. This will be an AJAX application, but you surprisingly don't need Javascript and a whole lot of XML skills to get it working.

The application I will build in this series is a solution to a current need of mine: it'll be a small scale project management application suitable for contract software developers to manage their tasks, invoices, and clients. That's it! Developers can set up projects and define tasks under the projects, give access to clients, and bill clients through the system. Clients can review projects and their progress, view status reports, get a daily email of work done on their projects, and pay their invoices online. Look ma, no papers.
Now I know there might be some super duper commercial product on the market that does these things, but the goal here is to learn to write one myself using these technologies. The whole project is built in Java. I'm calling this project TimeTrak, after an existing project I already have with the same name. This is like a 2.0 version of it.