Today I was reminded just how important documentation is, particularly End-User documentation... you know, the instructions for how folks are actually going to use your system.
In my spare time, I've been developing a very small system for a client (unfortunately not in Ruby/Rails, but that's another story). It's designed to replace one labor-intensive portion of their Commission calculation process, which is spreadsheet-intensive. You've seen them before: someone develops a simple spreadsheet to "save time" and eventually, the spreadsheet is a monster and the whole process takes days to complete and is fraught with potential errors. And with the sales reps watching the numbers like a hawk, nothing slips by.
The piece I'm replacing is for maintaining the Work In Process costs and pricing factors for the products developed in-house. It's a tiny database application which outputs an Excel workbook that is dropped into the monster spreadsheet and thereby replaces a very time-consuming manual update process. In fact, the process has been so challenging in the past that cost updates have been few and far between. The new system will allow them to make pricing changes at will.
Over the past few weeks, time permitting, I've developed small pieces of the system and run it by the client to make sure that my understanding is correct, and they've approved the prototype pieces that I've provided to them. This is actually part of my proposal process: try out important pieces of the system, and then let the client approve the results.
Today, I started writing the contract for the actual development. As part of the scope of work, I provided screen shots and a high-level overview of the procedural steps for using the system. As I worked through the steps in the workflow, I suddently realized that I was omitting one piece! I had prototyped that portion of the system early on and it worked OK, but the table I had created was only a dummy table, hand-crafted for testing, and I had not provided the necessary support for a user to maintain that table!
Fortunately I found this out before completing development and installing it for my client. At this stage in the game, it was pretty easy to add the required functionality and include it in the Users Guide.
You can call it what you want: Requirements or Design or Testing. Developing a Users Guide can help in all areas of your application life cycle methodology. In this case, I like to think of the Users Guide as being a form of UI Testing: I used it to test my prototype design (screenshots, data entry forms, reports, and output files) against the user interaction that would be required to actually do something productive with the system.
Does this apply to Rails? You bet! Just watch Jospeh Wilk's Cucumber presentation at Scotland on Rails 2009. He suggests that you "...think about the user interface first " and asks "...how is the business user going to achieve value through the interface?" He also stresses figuring out what's really important to you and to your user (see his example of "Popping the Why Stack"). I particularly like his question: "Have we achieved what the user wants yet?" It's all about a single-minded focus on the user of the system and the value that the system is to provide.
Fortunately my Users Guide test failed and I was able to address the issue today, not later down the road when it would be more time-consuming. And I saved a potentially awkward situation with my client.
So... I'm going to be more careful about writing Users Guides and testing the user workflow in the future...
When do you write your Users Guide?