Show Your Work

clip_image002I always hated math tests and math homework that required us to “show your work”. I was always of the opinion that I should get full credit for getting the right answer. Of course that’s because I was prone to say that (98 x 4) equals (400 – 8) instead of working out the pesky details of (8 x 4) and (90 x 4) and then adding the results. Today, I’m all about “showing my work”, but for a different reasons, I want people to know more than the results. What prompted this change of heart? Well, it’s been brewing over time, but one of two incidents this week pulls it into focus.

On Monday one of my coworkers told me about an error in one of our systems. The details revealed a coding mistake in 1999 that apparently had never been triggered. Apparently, the right combination of transactions had never been processed to cause the error to occur. My proofreader might point out that I used the word “apparently” twice in close proximity, but I did that on purpose – when you discover an error like this, you have to fix it and you have to make sure it never occurred before.

Fixing the problem was easy but making sure it had only happened once proved to be more difficult. The suspect transaction worked in all but a very specific scenario. That scenario can be characterized by various attributes in several tables, so I turned to my SQL query utility. This was the kind of problem that made me feel entitled to own Joe Celko’s SQL for Smarties, but when I was done, I had the answer – one solitary data row that was affected. The problem now was explaining that SQL statement. I needed to know this problem never happened before, but since I was fixing a production system, I also had to document that fact. Who reads that documentation? The auditors. I looked at that SQL statement and thought about trying to explain it to an auditor and I realized how futile that effort would be. I removed a few sections of my SELECT statement, rendering the statement readable and increasing the number of rows returned to 99. That seems like a lot of data, but it is easy enough for someone to review 99 rows and quickly determine that only one was involved.

OK, what does this have to do with SharePoint? Ironically, this same issue has recently surfaced in the custom list and custom library projects we have been working on. We have a number of columns that we use to control the workflows, columns our first instinct told us to hide from the user views. A little more thought on that subject convinced us that maybe we were planning to hide too much. For example, the workflows manipulate a number of dates that will be used to display summary information in a dashboard. Instead of hiding all of these dates, we may leave certain ones visible. If someone should look at the Dashboard and say “that can’t be right”, I’d like them to have an easy way to verify the information. Another example has to do with comments from people reviewing documents. This example is actually a two-fold case of show-your-work. We initially considered using the annotation features in Word for these, but since this type of content gets stripped out of the final document, we decided to use a Rich Text column instead. Here too, our first though was to make this a closed communication channel between the author and reviewer, but once again that would be a mistake. The comments provide insight into the reporting process. Rather than hope that people will read good reports and then magically know how to write good reports, we can show the thought process that took us from an OK report to a good one.

The more I work with SharePoint, the more I realize that an iterative review of the requirements with the users is essential to building good SharePoint solutions. SharePoint’s collaboration and business process support capabilities are so hard to understand from the user point-of-view, that it is incumbent on us to present work-in-progress back to the user and let them reconsider their expectations. Such discussions may lead to additional work, but we are finding that they also lead to much better solutions.

3 thoughts on “Show Your Work

  1. I would argue that in this day and age of sophisticated development and modeling tools, iterative development with the so-called "users" is an imperative. Few of those users are unable to express, at least in words (if you tease it out of them), how things ought to work. As developers, we're their partners and we all should arrive at the answer together. We all own it, not just the coders. Highly iterative, collaborative development greatly increases the possibility of arriving in the right place together. "Showing your work" should be an integral part of the process.M.

  2. Right on point Marc, but "Teasing it out of them" does get to be an art form. Early on, I pursued the goal of having the users own the system, I just wanted to build it and then move on. Last Friday, one of my users described us as having "joint custody" of the system – I told him I want weekdays.Dan

Comments are closed.