Our sales team often refers to our Hierarchy of Qualification when evaluating projects. This pyramid, inspired by Maslow’s hierarchy of needs, gives us the tools not just to evaluate the business needs of a project, but the human needs that are “encoded” in the project and team.
I’ve been thinking about how this applies to software development, particularly in the enterprise space. Enterprise implies that the software is maintained by large teams over long periods of time. Most developers have encountered internal enterprise software that leaves us shaking our heads, asking “how was this ever released?” Alternatively, we’ve used an internal tool that is quite good, but where the business has trouble repeating that success with new projects.
If we can describe the path towards self-actualizing software quality, we can elevate our teams from solving a series of one-off problems towards building value for our businesses and ourselves. It’s important to acknowledge that these steps are additive, meaning a team may benefit by mastering the lower rungs of the pyramid before moving on to the next.
Describing software and how humans will use it
This is the base of the pyramid and undergirds everything else. Before writing a line of code, a team needs to have a good handle on who the audience is and how the software will affect them, along with the overall goals of the new project. Often, enterprise teams are given work to do by their customers or their management with the explanation: “a big internal department has told us this is a blocker, so don’t ask why and get to coding, so we aren’t late.”
This leaves project managers and developers in the dark, and unable to make reasonable guesses when requirements and technology conflict. Knowing the audience lets teams prioritize their work when time is short. Is the audience a group of editorial users? What’s their day-to-day workflow like? In that case, time may be best spent on testing and iterating the user interface, at the expense of implementing every last feature request. Is the audience another group of developers? Then perhaps the project doesn’t require a user interface initially, so developers can focus on great APIs and documentation. Not knowing the audience may lead to otherwise avoidable mistakes.
Like audience, project or product goals are another important piece of the puzzle. When goals are fuzzy, it is hard to know when a software project is done, or at least at a “1.0” release. Teams tend to leave projects at a nebulous “0.x” version, making future developers uncertain about the quality or robustness of a system. For example, perhaps a client asks to implement Apple News and Facebook Instant Articles on their website. It’s a reasonable request. Nevertheless, prematurely ending requirements gathering at “implement the feature” deprives your team of critical information.
There’s a business reason behind the request. Is the analytics team seeing declining traffic on their website, and worried the website audience is defecting to social networks? It may be good to suggest working on Facebook integration first, assuming you have some analytics data from existing Facebook posts to back it up. Or, perhaps the sales team is hearing from advertisers that they want to purchase ads against your content inside of the Apple News app. In that case, finding out some rough estimates for the additional ad revenue the sales team expects can help with qualifying estimates for the integration effort. If the estimated development budget eclipses the expected revenues, the team can investigate different implementation methods to bring costs down, or even rework the implementation as a one-off proof of concept.
Using audiences and goals to guide your development team makes it possible to discover opportunities beyond the immediate code, elevating the team from an “IT expense” to a “technical partner.”
Technical architecture and documentation
Writing the right software for today is one thing. Writing maintainable software that future developers can easily iterate on is another. Spaghetti architecture can leave you with software that works for now but is very expensive to maintain. For Drupal sites, that means avoiding god-objects (and services), writing true object-oriented code (and not procedural code that happens to live in classes), and avoiding side effects such as global and public variables. It’s important to document (preferably in code) not just what you built but why you built it, and how the architecture works to solve the original business problems. Think of it as writing a letter to your future self, or to whatever team inherits your code.
Determining the effort to put into this work is tricky, and time pressures can lead to quickly written, but poorly architected software. It’s useful to think about the expected life of the application. Look at similar applications in the company and ask about their initial and current development. For example, in our CMS projects, we often find we are replacing systems that are over a decade old. The code has gone through many teams of developers but is in a decrepit state as the architecture doesn’t follow common design patterns and the documentation is non-existent. No one wants to touch the existing application or infrastructure because experience has shown that may lead to a multi-day outage.
In cases like this, we know that following good design patterns and effectively documenting code will pay dividends later. A marketing site for an event in 3 months? You can probably take a lot of shortcuts without risk. Treat the project for what it is—a startup within an enterprise.
A culture of iterative feedback
Defining the software to write and following good architecture in its execution is important but we can do more. Now that our efforts are well documented, its time to create a proper harness for testing. Without one, it’s impossible to know if your team is meeting your quality goals. It’s easy for teams to fall into a fragile, untrustworthy process for testing. For sites, that typically means not defining and following deployment best practices or creating a QA bottleneck through infrastructure.
The typical git model of development implies not just a few branches that are merge destinations (like master and develop) but many feature branches, too. It’s not uncommon for developers to create multiple branches breaking a single ticket into smaller code components that can be independently reviewed and tested.
For developers, “waiting for a QA build” is one of the biggest motivation killers they face. For QA, trying to coordinate testing of various features onto a single QA server is complex and leaves them questioning the validity of their test plans.
Just as “smaller, chunkier” pull requests are a best practice for developers, a similar guideline helps QA analysts feel confident when certifying a feature or release.
Tugboat is one tool that lets teams implement automatic, lightweight, and disposable testing environments. When a developer opens a pull request, a complete working copy of the website is built and available for anyone with access to poke at. It’s easy to rebuild new testing environments because the setup is automated and repeatable—not manual. A process like this extends the effective QA team by including both developers (who can reproduce and take ownership of bugs “live” with QA, before code is merged), and the actual patrons of the build—project managers and business stakeholders—who will eventually need to sign off on the product.
These tools also change the culture of communication between stakeholders and implementation teams. Even with two-week sprints, there still can be an information gap stakeholders face between sprint planning and the sprint demo. Instead, getting their feedback is as frictionless as sending a link. There are fewer surprises at demos because stakeholders have already seen the constituent parts of the work that compose the whole demo.
Automated tests and quality metrics
Frictionless QA is great, but it’s still a manual process. It’s incredibly frustrating for an entire team to be going through manual QA for regression testing. Sometimes, regression tests uncover the sort of bugs that mean “rewrite the feature from scratch,” leading to failed sprints and missed demos. That’s especially likely when regression testing occurs at the end of a sprint, leaving precious little time for rework and another round of QA.
In contrast, developers love when automated tests alert them to issues. Not only does it save developers and QA time (they can work on a new ticket while waiting for a test suite to run), but it reduces the cognitive load of developing a new feature in a complex application. Instead of developers having to become the application experts, and maintain that knowledge in perpetuity, the automated tests themselves become the legal description of how the code should work.
Comprehensive test coverage, regardless of the actual tool used (like PHPUnit or Behat), also helps ensure that software quality remains constant as underlying dependencies are upgraded. For a Drupal site, teams should expect at least two significant upgrades of Drupal per year, along with an update to PHP itself. Automated testing means the initial work is as simple as “upgrade Drupal, run tests, and see what breaks,” instead of throwing a bunch of time and money at manual testing. It also means that testing of security patches is much faster, saving time between vulnerability disclosure and deployment.
Of course, there’s a cost to automated testing. Tests are still code that need to be maintained. Tests can be buggy themselves (like that time I accidentally tested for the current year in a string, which broke when 2018 rolled around). Someone has to pay for a continuous integration service or maintain custom infrastructure. Reducing these costs is a particular interest of ours, leading to templates like Drupal 8 CI and the Drupal Testing Container.
Again, knowing the expected life of the software you write helps to inform how deep into testing to go. I don’t think I’ve ever written automated tests for a microsite but for a multi-step payment form expected to endure for 5 years, they were critical.
Technical architecture, for all of its focus on “clean code,” can rapidly devolve into unresolvable conflicts within a team. After all, everyone has their idea of what “good design” looks like. While automated tools can’t tell you (yet) if you’re using the right design pattern to solve a given problem, they can tell you if your app is getting better or worse over time.
Start with enforcing basic code standards within your team. Code standards help team members to read code written by others, which is “step 0” in evaluating if a given codebase meets quality goals or not.
For example:
As a technical architect, you want reading the code to feel as natural as reading written text — so
you can focus on the meaning, and not the individual words.
Think about how much harder it is to focus on the idea I’m trying to communicate. Even though you can understand it, you have to slow down and focus. Writing code without code standards sacrifices future comprehension at the altar of expediency. I’ve seen teams miss critical application bugs even though they were hiding in plain sight due to poor code formatting.
Luckily, while different projects may have different standards, they tend to be internally consistent. I compare it to reading different books with different fonts and layouts. You may have to context switch between them, but you would rarely have the paragraphs of the books interspersed with each other.
While code standards tend to either be “right” or “wrong,” code quality metrics are much more of an art than a science—at least, as far as interpreting and applying them to a project goes. I like to use PhpMetrics as it has a very nice user interface (and works perfectly within continuous integration tools). These reports inherently involve some subjective measure of what a failure is. Is the cyclomatic complexity of a method a fail at 15, or 50, or not at all? Sometimes, with difficult codebases, the goals come down to “not making things any worse.” Whatever your team decides, using these tools daily will help ensure that your team delivers the best product it can.
Continuous delivery
As a team addresses each new layer of the hierarchy, the lower layers become habits that don’t require day-to-day focus. The team can start to focus on solving business problems quickly, becoming an IT partner instead of an IT expense. Each person can fully participate in the business instead of the narrow field in front of them.
With all of these prerequisites in place, you will start to see a shift in how your team approaches application development. Instead of a conservative and fragile approach to development, your team will start to design and develop applications without fear. Many teams find themselves rotating between the bottom two levels of the pyramid. With careful planning and hard work, teams can work towards the upper tiers. The whole software delivery process—from ideas to releases to hotfixes to security releases—becomes a habit rather than a scramble every time.
Hero Image Photo by Ricardo Gomez Angel on Unsplash