“Design”

Uncategorized

The team I work on has been doing “scrumbut” for a while, and now that we are wrapping up the current project, we are trying to figure out how to fix it and do scrum going forward. In that context, I wrote this email to the team (why was that my job? I’m one of the technical leads…). Note that the “company across the parking lot” is Westinghouse – they build nuclear reactors – I hope they do a lot of big design up front! Also note that much of this idea stems from reading and digesting the works of Scott Ambler, particularly this one. Enjoy:

So, we still want to do Scrum. And plans are underway to get us back into the swing of it. Well, there are some things we didn’t do real well the last time around, and many of them have been identified. One thing we didn’t do very well at all that I’d like to address is “design”.

To some people, design means writing a 100 page document describing every possible thing that could happen on one simple data entry screen. That probably works fine over there across the parking lot, but its not particularly agile, so lets abandon that thought.

To other people (and the way we worked in 7.0 [our current project]), design means “I thought about it for a couple minutes, lets sling some code”. That doesn’t work very well, either. Sure, you can make things work, especially in the simple cases, but then most of the time you end up with stuff that is hard to follow, and isn’t optimal (in terms of any of the ” –ilities”: maintainability, scalability, readability, etc.).

So, what is the answer?

When you get a task that will ultimately result in writing code, you should sketch out what you plan to do. If it’s a simple feature (say, something like a data entry screen for something simple, like maybe a unit description), doing this exercise in your mind is probably sufficient. If it is a little more complex, a “napkin sketch” of any sort that you prefer (actually doodling on a napkin, drawing a little on your whiteboard, making a TODO list in notepad, etc.) is sufficient. Just make sure you don’t put a lot of time into it – its probably disposable.

Regardless of how you do it, keep in mind that collaborating on a design is not a bad thing. We’re not in college anymore – working with others is not cheating. Get in the habit of getting together with someone else and discussing your design. We’ve got whiteboards around (granted, the ones at our desks are entirely too small, but better than nothing). There’s plenty of paper in the supply closets. Get together and draw and talk.

What if you need to implement a hard feature, like ClassifyRequest, for example? I’d recommend using as little prose as possible – it gets hard to maintain. I’d suggest you create UML diagrams – especially Activity, Sequence, and State diagrams. Design documentation for a feature like this needs to live on, so it needs to be as easy to maintain and modify as possible. The huge, ugly design documents we write don’t satisfy this requirement. They are pure shelfware, in a totally Big-6 (or however many of those worthless huge consulting firms are left) kind of way. The alternative is to draw diagrams – a picture is worth a thousand words. Diagrams are generally clearer than prose, and far easier to maintain. They also help you resist the urge to get TOO detailed. Details at the design level are generally not helpful – the well-written code itself is the best way to define the details.

If you don’t know UML (or need a refresher/reference), this site seems pretty decent: http://atlas.kennesaw.edu/~dbraun/csis4650/A&D/UML_tutorial/index.htm. Don’t worry about getting it perfect, especially if its just a whiteboard sketch. As long as you’re close, people will be able to figure out what you mean.

So, going forward, we need MORE design. But we need the RIGHT KIND of design. When you think of a tool for design, think whiteboard or Visio, not Word.

Advertisements