Tools of the trade

1 Mar 2020
   

Posted by Comments

I've been reflecting back on the tools I've put in place for my current team, in anticipation of the next hiring in the team. I was wondering whether we would do a better job at integrating new team members than we did in the past for recent hires.

As a proponent of what I call "useful documentation", I wrote a massive amount of documentation. The most valuable to my eyes are, without any order:

  • A guide for installing and configuring a developer workstation;
  • A Troubleshooting Guide;
  • A Team Conventions Guide;
  • A long list of operational procedures; just about every technical task I handle gets its page on the Google Site, with the whys offering the most value.

Developer Workstation Guide

Believe it or not, there was no such guide. Installing a workstation for a developer was time-consuming, but the most salient problem was the fact that errors that had already been previously fixed show up all year long. There was no listing of all the software needed, from ActiveMQ to the database system to the outbound e-mail interceptor. Required environment variables were nowhere to be found.

Now, getting all repositories to the workstation is merely a matter of cloning a bootstrapping repository and running a specific script. What used to be memories of only part of the team is now written for everyone's benefit. What used to take days if not weeks or months to be a somewhat complete environment is now installed and configured in less than a day. One day of work for several months or years of tranquility (except for updates) is time well spent, in my opinion. Once done, it is done well. And forever. Or almost.

In the past two years and a half, it has been regularly updated by the team. But more importantly, it has been used more than a dozen times to set up development workstations.

Troubleshooting Guide

This guide was an instantiation of an old habit of mine: building my own knowledge base, to avoid doing the same Web searches again. Why build such a document in a team?

  • To save time for the next time the error is encountered by a team member.
  • To share knowledge.


There is another reason that I never told the team about: adding a stone to the team spirit edifice by benefiting from someone else's contribution to the guide.

The idea is that each entry of this guide contains an error message (or an excerpt), the cause of the error and the fix (or fixes). Unfortunately, I see the most value in the cause, whereas developers often see the value in the fix to the problem. It is striking to see the kind of entries that they add to the document; there's usually no cause. That means that there is no knowledge to derive from those entries. Sadness is the name of my emotion then, at the very moment I browse the document and come across one such entry. Then, if I can identify the person who added it, I take note of the entry and have a discussion with them to have the cause written down.

Team Conventions

This document covers many kinds of conventions, from code style to branch naming, mainly conventions that cannot be enforced or verified by IDE tools such as SonarLint. It also contains my gospel for items I believe are important, e.g. documentation, automated testing, checklists and comments. It does a pretty good job of explaining how things work. We rely on the each individual's conformance to agreed-upon rules.

But what good does it do?

At the end of the day, every piece of documentation can only go so far. The rest of the path relies on team members helping other team members get up to speed, and each person giving it their all because they believe the documentation is a good thing. The devil is in the "believing" part.

 If we don't collectively believe, I wonder how we are going to create a culture of sharing that any newcomer will sense and adopt because they benefit from it and, say (to my delight) to the next new team member "you know, that's the way we do things here".

 


Tags :