Skip to main content

For Reasons Unknown

Posted by editor on September 8, 2008 at 6:10 AM PDT

Should you have to understand the application you're writing?

Extreme Programming has a concept of user stories, which express the customers' needs for the application you're writing. In XP, they're used only for estimating development times, yet have a very different feel than traditional requirements documents. It's very different to program to someone's narrative of how a system should work, as opposed to the traditional process of checking off items on a requirements list in your cubicle.

Now let's take this a step further and completely invert the process... instead of checking off your requirements, delivering the app, and documenting it for your users, what if you started by writing the manual, and used that as your requirements / design docs / user stories?

This approach is described by John Reynolds in his blog User Manual Driven Development.

Our development methodology was simple but effective... the marketing group wrote the deskmate user manual and we built the applications to match the manual. To be more precise, the marketing group would write a proposed manual, we'd negotiate with them over what could and what couldn't be done, and then we'd build to the manual.

I guess you could call this User Manual Driven Development, and I think that it still can be a very valid approach. In most respects User Manual Driven Development is very close in spirit to Test Driven Development - The function of the software is clearly defined, so it's very clear if the software doesn't do what it is supposed to.

In the spirit of TDD? I imagine the agile types are having a heart attack at the very thought of this, as it's clearly a case of Big Design Up Front, if not Waterfall. But still, if you think about it, you can see some appeal to this approach. One thing you might get out of this approach is a better understanding among your developers of what the app is really supposed to do -- beyond the clinical requirements list check-off -- since it's written from the point of view of how the user will use the the application, and implicit in that, what value they'll get out of it. As John points out:

It always stuns me when I encounter an engineering manager who believes that his staff doesn't need to know how to use the product that they are developing. I've heard people say "Just give us the requirements an we'll build it". I simply cannot agree with this philosophy... Requirements are never enough. Ever.

To write great software, you have to put yourself in the shoes of the user and walk a few miles. Perhaps it's a bit like method acting... Unless you "become" the user you're just going through the motions.

John points out that some of the best software is that which is made for developers, because developers know what other developers want and need. It's a lot easier for a typical developer to know if their IDE is useful than if they're building an accounting package, a non-linear video editor, a medical imaging system, etc. But if you have to build something like that, maybe a good first step is to start with a user manual for the finished project, so you can understand what the user will get out of the finished app. To steal a chapter from the famous Seven Habits of Highly Effective People, this is literally beginning with the end in mind.

But would it work for most people? What do you think?

Also in today's Weblogs, Cay Horstmann shares
Lessons from My Summer Vacation. "In this blog I reflect on what I learned during my summer vacation, about standards, folding travel beds, and snatching defeat from the jaws of victory."

Arun Gupta wraps up a series of conference report blogs in
Rails Conf Europe 2008 - Day 3. "Last day of Rails Conf Europe 2008 (Day 1 & Day 2), and it's finally over!"

In Java Today, has released a new patch, which is an update to the NetBeans IDE 6.1. "The patch includes bug fixes in modules for BPEL, C/C++, Composite Application, Database, Editing Files, GUI Builder, GlassFish, IDE Platform, Java, Java EE, Java Persistence, NetBeans Plugin Development, Platform, RESTful Web Services, SOA, TAX Library, WSDL, Web Services, XML Productivity Tools, XML Schema Support, XML Tools Java Ext, XML and Schema and XSL Support." To obtain the fixes, the NetBeans IDE must be installed and running. You can download the fixes through the IDE's Plugins Manager.

Ever wonder what JSRs and Java technologies are supported by what devices? "The Java ME technology Device Matrix is a compilation of publicly available information from third-party sources, from Alcatel to Nokia to TTPcom. Go to the Authorized Licensees page to see the java ME licensees who claim compatibility with Java ME specifications and TCKs."

Danny Coward says he likes to get in some Java news even when he's away from the keyboard, and has compiled a list of top Java podcasts in Java Podcastapalooza! "For those of you who are interested and are looking for something new to tune into in the area of Java and client technologies, I put together a little survey of the ones I subscribe to. And if you feel like it, let me know if you have a top podcast in a comment below."

We're repeating last week's Spotlight to remind you of a major schedule change. The second Java Mobile, Media & Embedded Developer Days will be held January 20-21, 2009 (note the new date) at Sun's Santa Clara Campus Auditorium. "This conference is devoted solely to the technologies of mobile and embedded Java platforms and will be a unique opportunity for application developers of intermediate and advanced skill levels, platform developers, and technical experts at tool vendors, OEMs and carriers to get introduced to the community, to join in and collaborate." The Call for Papers, announced in Roger Brinkley's blog, is underway now and will end September 30.

In today's Forums, Kristian Rink explains practical advantages of the Java Persistence API in the follow-up Re: What's advanteges of JPA? Basic question about this technology. "JPA doesn't require to run inside an application server, actually you can pretty well use it for standalone applications. So overally this migration would be alot easier than, in example, following your managements decision to use DB2 rather than Oracle in the next release while having built all your application logic directly to the database."

cowwoc appeals for resolution to a long-standing shutdown hook bug on Windows in
Re: What would it take to fix bug #4486580? "I posted a workaround near the end of the bug report (using a JFrame) that turns out to be unreliable. Seeing how this bug is 7 years old, the fix is well-understood and that there isn't a workaround for it I would really love to see it fixed in the near future. It is even more relevant in light of the recent "Java on the Desktop" efforts."

skyslee2005 wants to know
how can i port phoneme feature to another platform(no win32, no linux). "my platform use mips process and a sample realtime OS,so i don't know how to port phoneme feature on it. as far as my understanding of phoneme feature,the javacall api layer only run on win32 platform, and i don't konw how can i build prerefiler and other tools for my platform; the makefile may have to change much place;for cross complier,there may be many work have to done,but i have no idea."

Current and upcoming Java

Registered users can submit event listings for the href=""> Events Page using our href="">events submission form.
All submissions go through an editorial review before being posted to the

Archives and Subscriptions: This blog is delivered weekdays as
the Java
Today RSS feed
. Also, once this page is no longer featured as the
front page of it will be
archived along with other past issues in the href=""> Archive.

Should you have to understand the application you're writing?


"That's why we have business analysts ;-)"

That's why a previous employer had all people working fulltime on their prime product (which was a system for reposession/collection agencies) get a degree in accounting, and paid for the training during work hours.

That might be taking things a bit far, but the people writing the system should have some understanding of how it will be used, else they can't know if what they're creating makes sense, nor if the test results (you do do unit tests I hope?) make sense.

User manual-driven development seems to be predicated on the idea that marketing people can design software (and write user manuals). While (IME) they are great at eliciting user requirements and inferring "real" requirements from wish lists, I wouldn't let them run wild. We're actually having a difficult time on my current project due to the fact that one of the project's sponsors from pre-sales insists that we include UI features that aren't supported by our (in-house AJAX-based) GUI framework. He pulls up sites at random and points to features they have and says "I want [feature X] to work like that". I understand that there's some give-and-take between marketing and engineering, but wouldn't it be better to simply drive more involvement with marketing during requirements definition? Or let them play proxy users when collecting user stories?

"It's a lot easier for a typical developer to know if their IDE is useful than if they're building an accounting package" Which is s good reason why the proposed methodology has limited use. I am currently on a contract in an insurance underwriters. I am working on their accounting package and for me to understand everything about how the software is to be used and why I would basically need a degree in accountancy. That's why we have business analysts ;-)

"In the spirit of TDD? I imagine the agile types are having a heart attack at the very thought of this, as it's clearly a case of Big Design Up Front, if not Waterfall. " Which goes to prove that Test Driven isn't just applicable to Agile... Test Driven (as I understand it) is about developing the acceptance test before writing the code.

"Not for reasons unknown. Look. I told you we set down there on company orders to get this thing that destroyed my entire crew, and your expensive ship."