SOEN 390 - Post-mortem
Posted by Skrud at Monday, April 17th 2006 at 12:47am
This software design course lasted throughout the entire semester, with the intention of taking virtually everything we’ve learned up until this point and applying it. This year, things were done a little bit differently. The amount of freedom previous semesters had had in terms of choosing their projects and implementations was reduced. In fact, we were given a project and a platform to work on. We had to interview our “stakeholders” to get a detailed list of requirements, and from that see our projects through until completion. Requirements would change, and we’d be expected to keep up.
I learned a huge amount from working on this project, and so I figured this would be a good place to jot down (in a slightly more organized fashion) what I think was great about the project and where we fell short.
You’ll have to click on “Read More” below to see the full post.
The Project
The project we were given was a Task Manager, and its target users were professors, TAs and students. Users should be able to add and remove “tasks”, set due dates for them, assign tasks to other people, create “journal entries” for those specific tasks and so on. (I’d link to a copy of the Vision document and Use Case documents here so you can get a better idea of I mean by tasks, journal entries, etc. but I only have hard copies lying around – I can’t even find a good online resource to explain what those documents are).
The project was split into two releases. Release 1 was due sometime in March and Release 2 was due at the end of the semester. Each release was coupled with a demo. I think the two-release system was mostly beneficial, since it meant that we’d get some feedback and have something to build on before the final project is due during the semester’s typical crunch time.
Our “customer” basically consisted of Stuart, so we’d need to clarify our questions by talking to him. We had to schedule interviews with him and meetings to figure out exactly what it was our software needed to do. After Release 1, we had access to a User Interface Expert as well: Kristina Pitula. We met with her in order to discuss how our interface was shaping up and where we could improve it.
MyTeam
We formed our own teams. Our team was called “MyTeam” (and our product was called “MyScheduler”…). I think we were a pretty solid team, my teammates being: Alex, Tahir, Olivier and Dave. (Tahir and Olivier really need websites).
Structure
Our team didn’t have a team leader. I think this was ultimately the source of one of our biggest problems. A lot of times while developing, we’d be faced with decisions that needed to be made. The lack of a leader meant that a lot of questions were left unanswered until the last minute, and a lot of decisions were left up in the air. There were some required features that we never got around to implementing since we never decided on how to implement them. While the no-leader system worked great for the last big project, it crumbled under this one.
Organization
Somewhere near the middle of the project I set up a Basecamp account for us. It’s kind of ironic that in the middle of working on a Task Manager, we’d need to be using a task manager. Basecamp is wonderful. It was extremely useful for sending messages to the entire team and recording the results of meetings (such as interviewing Stuart and Kristina). After long nights of coding I’d often send out a lengthy message thru Basecamp listing a lot of the changes I’d made, and some questions raised. But – then I’d forget about the questions and they’d never get answered (see the above paragraph).
Documentation Driven Development
One thing that bothered me about this project was the emphasis on writing documentation!!! Now, documentation is not inherently evil. Yes, it’s a pain, but ultimately we *do* need something that tells us what we’re building and how we’re building it so that we can stay on track.
Too many documents
We had a lot of documents. I mean, a lot. Our Software Architecture Document was something like 80+ pages. On top of that we had: a Vision Document; Supplementary Requirements and Specifications; Use Case Document; a Style Guide, a Test Plan, and many more.
There were so many that it was impossible for me to keep track of them, and a lot of the information was overlapping. The Vision Document would mention the Use Cases which were detailed in the Use Case Document and realised in the Design Document which was detailed in the Architecture Document…. And this was nothing but a small task manager in an academic setting. I can’t imagine what these documents would’ve been like for a larger-scale project!
The very fact that there were so many documents containing so much information that it was unmanageable is a problem. I felt terrible for Tahir and Olivier who spent most of their time working in MS Word – I’m not even sure they got to see a line of code.
Traceability
Every time a requirement changed, resulting from an interview with Stuart, or every time a decision was actually made, we’d need to update all the relevant documents. Everytime there was a change in design or an addition of more architecture-related classes we’d have to update the documents, make class diagrams, and tons more. In the strictest intentions of “Software Engineering”, one is supposed to go from documents to code, not the other way around. But we didn’t have the time to develop all the documents first, especially since our architecture document was supposed to be a submission for our architecture course, due a few weeks after the demo for Release 1.
Opportunity Cost
I’m scared to try and count the number of hours spent maintaining documents. I think the opportunity cost is extremely high considering that Tahir and Olivier could have been working on actually getting our software working. I wonder how much time was spent fiddling with MS Word and all its quirks, too. The very fact that concurrent versioning tools (like CVS, which were using) can’t diff and keep track of binary files like Word documents made it much more difficult to maintain those documents, and we had a lot of trouble exporting class diagrams I made in OmniGraffle into MS Word (which really should support PNGs, TIFFs and PDFs but apparently doesn’t).
Documenting only as needed
I think instead of following a strict document plan, like we had to do for this project, one should follow looser pattern. Basically, only document what you need. Whenever a design decision is made, write it down, and the reasons for it. Whenever a question is raised, write it down – along with the solutions as they come along. I think a blog would be the best way to keep track of a project (especially if the team is small – say, up to 10 people). Whenever someone is up coding all night, they should blog what they’ve done. The next morning when the team memebers wake up, they’ll check the blog and see what decisions were made, what was changed, and what was updated.
Even better than a blog would be a system designed exactly for this purpose. Like Trac. Oh, if only we could have used Trac!!!
Architecture vs. Application
What was the purpose of our project? What was the ultimate goal we were working towards? We had an application to produce, of course. A task manager. But that’s only the top-most layer of what we were doing. What we really had to do, was implement and create an architecture for a web-based application. This is a distinction that only became clear to me in the last week of the project, but it’s a very important one.
The Architecture
The architecture, as I see it, is the foundation for an application. It’s the underlying core that drives the application. The application might have concepts like “Tasks” and “Journals” and “Users” and “Categories”, but the architecture will only see this as things. Things to pull from the database, things to keep from overwriting each other (concurrency), things that interact – but the architecture shouldn’t know how they interact. The architecture should only be concerned with how these things are organized internally, transparent to the application. (I’m going to use the terms “architecture” and “framework” interchangeably here).
Rails is an architecture. This blog, Basecamp, and 43Things are applications that use the Rails framework. Rails is the same for all of those applications, the only thing that makes them unique are the concepts they define above the architecture layer. Blogs have posts, comments and trackbacks. Basecamp has projects and milestones. 43Things has … well, things.
We had to build our own framework, which means that we had to desgin our own architecture. We were given some beginnings to work with, our “SoenEA2” Architecture in J2EE, but it defined nothing more than a Servlet and a Command-pattern. There are frameworks for J2EE: Struts, for example. But we were building out own. Building a framework is a huge amount of work.
On top of that architecture that we developed, we’d have to write our task manager.
For the sake of learning
I might sound like I’m complaining, but I really learned a great deal from the challenge. Writing the application on top of an existing architecture would have been trivial compared to what we had to do. Writing the architecture forced to apply concepts fresh from the classroom into our project, and make them work. In the end, I think I have a much better understanding of how these architectures (like Rails and Struts) actually work, and that can only make me a better programmer when I have to use them.
I also learned that if my ultimate goal is to develop an application, that I should not waste my time developing an architecture to support it. That kind of effort is akin to reinventing the wheel. In the case that no existing architecture supports my needs as an application developer, then (and only then) would I delve into architecture development. But I would make my architecture as independent from the target application as possible – in fact, I’d make it a completely separate project if I could – so that in the future, I could develop more applications on top of that architecture.
What I don’t think was clear with our SOEN390 project was whether the goal was to develop a task management application or a web-based application architecture. Ultimately every team had to develop both, but I think that the difference between the architecture and application should’ve been made clear and stated at the beginning of the course… at least, it’s something I wish I could’ve seen sooner.
It’s Over
I’m glad this project is finally over. It became tedious after Release 1 came out, and I lost a lot of my drive and will to work on it – to the detriment of the project, I’m sure. It also cut into the time I could’ve spent working on my other courses. Suffice it to say, I’m absolutely sick of J2EE and Tomcat. I never want to touch either of them again.
You can see my project for as long as Stuart keeps it on his server: http://stu02.encs.concordia.ca/group8k/user8k4. Log in with the user name “Alice” and password “wonderland”. (Or you can log in as “Chuck” with password “walker” for an easter egg.)
