Skip directly to content

Documenting the Deltas: a response to J. Lambert's "On containing risk vs getting things done"

Kelly Bell's picture
on Mon, 03/14/2011 - 5:24pm

I was so pleased to read this article by the inestimable Jonathan Lambert of Workhabit fame: I couldn't agree more with Jonathan (which doesn't surprise me, since he's a mr. smarty pants, and by "mr. smarty pants" I mean to say that he is an extremely thoughtful, intelligent and original thinker and problem-solver). I've often struggled with the documentation issue with clients both potential and actual, and trying to clearly express why spending two weeks and 100+ pages documenting a Drupal project is such a profound waste of time is an ongoing challenge. Especially since it's also true that I absolutely loathe doing it (a very bad business reason, right? Well, maybe, maybe not. Read on...)

I should perhaps insert an anecdote which serves to reinforce Jonathan's point (read that article!) about (ir)relevance. I once took over working for a client who had been given a "complete" Statement of Work by their vendor, after initial "discovery" had been completed - the same vendor for whom I was subcontracting. Several months after beginning the project I was given this SOW to review. I read, with considerable astonishment, a description of a project that had probably been developed by SOMEONE at some point in time, but certainly not for THIS client. It was for a project created in, for one thing (this was a Drupal project), and not a single one of the user flows, functional requirements, user interface or database designs had any relation whatsoever to the project at hand. I can tell you, this was a real jaw-dropper for me. It hit me hard that clients are at our mercy, and we cannot possibly be serving their best interests if we're providing such unintelligible documents that they couldn't clearly see that they'd been given completely erroneous information. I realize that this behaviour cannot be commonplace (please God I hope not!), but nevertheless, the point was well-taken, and I never want to be someone who rewards a client's trust and good faith with an unintelligible pile of impressive-sounding but worthless buzzwords.

I've come up with a solution which works for me: I call it "Documenting the Deltas", and while it's still documentation, the idea is that it's a compromise which gives the clients a balance between having *something* written down without being so detailed as to be out-of-date the moment it hits the printer. 

Here's the reality: once you're a seasoned Drupal developer, the scoping and estimating of every project - the "recipe" - comes down to a few basic ingredients:

  1. What "flavor" of Drupal should we start with? (Drupal 6 or Drupal 7, Acquia-Drupal, default Core or Pressflow, COD, Commons, Gardens, OpenPublish, OpenAtrium, OpenPublic, Managing News, and/or in which combination - this is our "Core Project" ingredient)
  2. Secret Sauce: We all have our own varieties of "secret sauce" we apply to each project which is comprised of various custom and contrib modules, methods, customizations and best-practice doodads which we know will make the site run better, in both dev and live environments, and which every client receives automatically as a benefit of our specialized knowledge and experience.
  3. Additional functional requirements (custom or contrib modules)?
  4. Custom Theme?
  5. New Design?
  6. 3rd-party Integrators (CRMs, Chat Servers/Clients, Meetups, eCommerce systems, etc.)?
  7. Anything else?

Once these questions are answered, we all have our ways of estimating effort and time, budget and deliverables. I've shared my methods with other experienced developers, and we all use some variation of this theme. This begs the question, "why document ALL of this, when these are constants, which vary only around the amount of customization and integration required?"

Hence "documenting the deltas", which is actually a simple concept: I take as assumptions the out-of-the-box functionality of all the component systems, and document only the pieces that are exceptions, or "custom" (integration, theme, design, functionality). When I am working with clients during Discovery, I make sure I show them how all these component systems work by default, and explain that we're going to be paying attention to the differences (deltas) only.

This is a giant step forward from the "waterfall" or "wagile" ("waterfall" masquerading as "agile" - by far the most commonly-seen method in the wild), for developers and for clients. This method allows us to dig deeper into and expose the areas which will require the most attention, and for which the user behaviours have no predetermined default. Suggested solutions are also detailed, allowing that we may very well find it's necessary to alter our approach based on any number of factors (usually having to do with the effects of complex, interacting systems). It also allows us to document changes to the user experience, data model, user flows and any other areas in the resulting system for which we wish to implement change.

There are certainly still challenges to be overcome in using this method. There are challenges around producing wireframes and user flows, for example. My solution has so far been to use an existing live Drupal install (using whichever "flavor" of Drupal is defined for each project in item #1 above) as a documentation artifact, similar to a clickable prototype. Similarly, with the design process I am far more interested in showing the design/theme to the client in "real" form, and apparently I'm not the only one with this idea. At DrupalCon Chicago there was a session suggesting this very technique: I am always in a process of continuous improvement (as in life), but initial results are very promising.

I would especially love to see some iteration on this approach in the hands of other experienced developers, and together we can perhaps integrate these experiences into a system that can perhaps reduce pain and increase relevant information, so if anyone has any thoughts on this approach and would like to share, I would love to hear your feedback.

On a final note, I described above my "loathing" of the traditional process of waterfall documentation. Sensible self-reflection might suggest it would seem prudent to be highly suspect of any activity which promotes aversion - after all, it probably just means that I'm terrible at it, right? But a funny thing has happened, over the 20+ years I've been a developer: I've actually begun to trust myself. I've discovered that when I really hate some activity and think it's a useless waste of time, it turns out to be accurate (que surprise!). So several years ago I embarked on a mission to actively find better ways to perform onerous tasks - to make peace with them by taking a creative second look at the root of the problem, and actively trying to find a better solution. Invariably, this revised approach makes the process not only tolerable, but useful - delightful, even. The lesson I learned from this is also a simple one: if a process or procedure is hateful, painful, and useless, trust yourself and change it - your clients will thank you. Remember that in the end, they're our audience.