Just-in-time collaboration trumps documentation
Yesterday, I created an entirely fabricated 2x2 quadrant chart about approaches to communicating and upholding development standards.
Let’s take a look at it again, now with an attempt at clustering:
There are three groups here, each with their own slightly different aims:
Pre-emptive education in the form of on-boarding, documentation and even in-person group training*.
Reactive conformance with automated static analysis tools and production monitoring.
Just-in-time collaboration approaches such as implementation planning, pairing and code review.
I believe the third of these - the just-in-time collaboration activities - are the most valuable.
If you’re just starting on a completely greenfield project or want to quickly and drastically improve your code standards and quality, it’s right in the middle of the process that you should start.
Don’t get distracted and spend weeks on beautiful docs or setting up extensive custom automation. Work together to experiment with new standards and guidelines so you can iterate on them. Take notes as you go and discuss what you learned. Make decisions quickly on non-controversial or low-impact items and ‘outsource’ as much of that work to open source or third-party tools so you can focus on the really meaty stuff.
You need to pay attention to whether standards and guidelines are applicable, learnable, simple and valuable (i.e. create good outcomes in the product).
Even if you are taking inspiration from elsewhere (and you probably should), standards start out as hunches, opinions and hypotheses. They need to be tested in context.
Once you have some stability and a good shared understanding you can formalise standards in docs and tooling, with the continued help of the whole team of course.
Remember that standards and guidelines should only be in place where they prevent harm to or benefit the constituents of the system: users, customers, the wider organisation, and the development team. They are not a stick to wield against non-compliant employees for the sake of toeing the line.
Perhaps reviewing your standards and guidelines could be a good New Year activity for your team.
All the best,
[*] - Back in 2000, I was working for an agency working on some Hewlett Packard sites. When they rolled out a new global style guide and manual, they invited about me and about 100 other suppliers to Frankfurt for two days of training. It was… dry.