Overview - acquia/drupal-spec-tool GitHub Wiki

Revered management thinker Peter Drucker once wrote, “If you can’t replicate something because you don’t understand it, then it really hasn’t been invented; it’s only been done.” In many ways content modeling in Drupal has been done without being invented. There is no accepted method of analysis, no common format for specification, no process for change management, no best practices for testing. Consequently outcomes are highly variable. For this reason, we’re developing a discipline for content modeling at Acquia. It’s drastically reducing both costs and defect rates for us, and we’re sharing it with you here.

Why a Specification Tool?

A standard specification format is an industry’s answer to the difficulty of validating, communicating, and conceptualizing complex solutions. Every professional domain has theirs: Object Oriented programmers have the UML, architects and engineers have the blueprint, and mathematicians have mathematical notation.

Without the blueprint, architects couldn’t validate a building design without actually constructing it; they couldn’t communicate it for execution except in lengthy prose; and no one could understand or reason about the design except by directly inspecting the in-progress construction. Anyone who has watched Drupal content model details pass from customer to technical architect to implementer to QA will readily perceive the parallels.

Jira (or your favorite ticketing system) is not a good tool for specifying a content model. It’s great for managing the work of implementing one, but it’s not made for clearly presenting extensive technical details that change over time. It does nothing to help you ask the right questions when you’re with the customer (much less format the answers). And when someone later asks what the customer decided on a given point, you don’t want to have to search through tickets to find an answer that may or may not have been changed in a comment or a later ticket.

Why a Spreadsheet?

Because everything is a spreadsheet, really. The human brain seems to be wired to understand data in grids. Want to spot patterns in a complex data set? Arrange it in columns and rows. There’s a reason we learn our multiplication tables in grade school.

We chose Google Sheets in particular for its sharing and collaboration features, including access control and commenting.

Do I Need It?

If you’re not meaningfully customizing the out-of-the-box content model of the Drupal distribution you’re using, this tool may be overkill for you, like creating a blueprint for your mobile home. But the more important your content model is to the business, the more complex it is, the more often it changes, and the more people need to understand it, the more specifying it will pay dividends.

How much dividends, you ask? We wondered, too, so we ran some numbers. On a recent large (Drupal 8) enterprise build we asked developers to estimate the amount of time they ordinarily spend per week on content model related activities, including implementation, communication, and change management. The reported average was eight hours per person. That felt low to us, but all the better.

Next we introduced the tool and tracked hours performing the same activities. After some basic training, we averaged five hours per person per week, about a 38% savings. The rate of change to the content model remained basically constant over the course of the project, ending with a massive 165 content entity type bundles, 630 fields, and 246 relationships (what a perfect test!), so we extrapolate that, given ten people over 46 project weeks with an hourly billing rate of $150, we probably saved over $200,000.

Numbers aside (stunning as they are) the consensus on the dev team was that they would never go back to the old way of working. As one developer humorously put it, “Words cannot properly express how chicken-with-its-head-cut-off life is without this system.”