The importance of the methodology over the tools

Some months ago, I’ve made a series of articles about the misbrands, a collection of brands logos derivations that put a name onto the logo of a competitor product. They were really fun for me and I’ve put some on my work laptop. Curiously, it took some times to have somebody noticing the wrongness of these pictures.

Ubuntu with Debian logo - license CC-0

Some purists didn’t like these images, but it was for me a nice opportunity to explain one of my work principles. I’m working as an IT architect in CICD patterns and DevOps culture. Our goal is to provide a software delivery methodology, standardize it as much as possible for reusing, and also unifying the tools used in this context. At the beginning of one of my missions, there were various directions in the IT department that were working with CICD patterns. Some were actually developing specific software, and other were integrating and using the continuous delivery and deployment patterns to package and ship into the Information System softwares originating from the market.

Because of a lack of direction in these practices, almost every team had their own CICD platform, work usage, and tools. Some of them were nicely organized and others were really amateur because of a lack of knowledge or investment.

So, our mission was to collect the various uses cases and construct a delivery model that could be applied to the whole company instead of everyone living their life in their corner of the information system. Of course, we choose a tool chain according to the uses cases and if some teams were already using they tools, other not. And I’m sure you know what’s happening when you ask for someone to change their habits… They panic, pull the emergency brakes, and cry because they don’t understand why you want to remove them their toys.

Crying baby, opencliparts, Public Domain

By the way, during project construction, we had some people asking if we had already choose the tools while we were still collecting the use cases. When you focus too much on the tool you forgot the essential : what do you want to do ?

• We’ve made our choice, it’ll be a bike !
• Nice, we need to cross the Atlantic Ocean

¯\_(ツ)_/¯

Then, after the use cases were collected and the choice made, we’ve explained something to the concerned teams : your tools are disposable, the most important thing is how do you work.

Let’s use a stupid example : a hammer is a tool. Whoever the manufacturer is, its purpose will remain the same : planting nails. The IT tools are the same thing. Of course, more complex and some have their custom ways, but basically : GitHub, GitLab, BitBucket, Gitea are all Git-based source code repositories. So you should not force yourself to stay on it because “we’re used to it” even if it’s a bad choice (common example : a poorly maintained self-hosted GitLab installed one day that became an important tool, but a security concern and a chore, or a risk when it crashes).

Rares were the teams who had written their work methods, their habits, practices, and methodologies. The documentation was minimalistic and mainly tool oriented. Basically, they documented how to use the tools, and not their work.

When you buy a furniture at Ikea, do you want the instructions to tell you how to assemble it, or how to use the screwdriver ?

The branching method, the merge strategy, the code review process, the delivery process, all of this was documented (when it actually was) according to the tool and not according to how they manage these parts. The real methodology knowledge was mostly orally shared and not written.

So, instead of hearing them saying “we use GitLab for…”, “we use SonarQube for…”, “we use Nexus for…”, we asked them :

• How do you implement a new feature to your code ?
• How do you implement a fix to a production code ?
• How do you test your code ?
• How do you store and install your artifacts ?
• How do you deploy your application ?
• …

The purpose of these questions were to help the teams to write their methodology and let it live and evolve. You use Jenkins to manage your CICD pipeline ? Explain what they do ! Despite the differences between Jenkins, GitLab CI or GitHub Actions, they’re basically doing the same things : scheduling and chaining tasks according to events. Same for an artifact repository : their purpose is the same, so you don’t have to explain how do you use Nexus or Artifactory but how do you manage your artifacts.

Of course, it’s still important to document how do you use your tools. But, if you have documented first how do you work, a lot of tool-oriented documentation can become useless. Typically, if you document the definition of done in your methodology : at what moment can we consider the developer has finished their job and can ask to merge the produced code ? What is expected in a code review ?

I’ve seen documentations saying : “you connect on GitHub, open a pull request for your branch, and assign the team for the review” with screenshots and on. OK nice, but GitHub has already documented this, so why rewriting their doc ? Something more interesting for me would be, for example, a simple checklist of what the developer should do while opening the pull request :

• I’ve made a self review
• I’ve tested my feature on the dev server
• I’ve updated the documentation
• etc

That may sound obvious for a lot of people, but the obvious things are sometimes the most forgotten ones.

Another reason why I think a well documented methodology is more important than the tools is to help a new teammate integration. I’ve often seen the integration of a teammate to be just reproducing what their mentor does. I was sometimes wondering if the new guy did really understood what he was doing. When your work habits are correctly written, you also understand how do you work. A side effect of a well-documented work method while enrolling a new teammate is also to have some feedback on it. Which put me to another interesting purpose of a good methodology documentation : to challenge it, take some step back and ask some questions. “Why are we doing like this ?”, “Wouldn’t be better to try this ?”, etc. Also, a reference documentation is important to ensure everyone in the team is working in the same way. I’ve seen countless examples of undocumented work methods conducting to have everyone doing their way. And in these case, you say hello to the merge conflicts, disappearing features, introduced regression, etc.

So, to conclude, my opinion is that the tools are disposable, the methodology remains. Especially in the IT solutions and the DevOps culture where the tool chain is evolving at the same speed as the patterns do. The developers and operational need to adapt regularly and embrace new tools and apprehend new usages. But basically, the job is still the same … So instead of trying various tools and try to figure out how to use them, ask yourself first what do you want and how to do it. Then, the choice of the tool will be a simple formality and you will avoid to lock yourself in the wrong one.