My Fondest Coding Memory: How a little, concrete step changed the whole culture
In this series, Omoroi staff members share their most beautiful coding memories. Omoroi CEO and DevOps architect Aleksi Aalto kicks off the series by telling a story of how small concrete changes can significantly impact a team's culture.
New product, old habits
I had the privilege of being part of a team building a new product. I was working in a big company at the time, which meant I rarely got to do anything from scratch.
As usual, the work was organized so that the developers worked on the product, and document writers did the customer documentation. This documentation is essential as it tells users how the product works. In this case, it was used by integrators who set up, maintained, and updated the product for customers.
Product development and customer documentation are often done entirely separately from each other. At best, one of the developers is aware of what happens with documentation. Most of them are totally clueless about it. Also, people doing documentation are only sometimes familiar with the developers' modern version control systems and practices. The documents are often sent back and forth without anyone really knowing which version is the most current or up-to-date. People try to track this down in long email chains and coffee break discussions. This messiness is partly why many developers refrain from involvement with the documentation side, even if that would benefit the outcome.
Bridging the gap: Integrating documentation to development
We had nurtured a dream of combining development and customer documentation in the same version control system for years. One day, we were going through the company's massive repositories. To our surprise, we found a promising tool. It looked like it could translate the common Asciidoc format to the format used by the company's customer documentation system. Amazed we looked into it, and yes, it really was a ready-made tool just for this! We tested it, and it worked perfectly.
We faced an epic battle of convincing all relevant people in the company that we should deploy this tool. As typical in big companies, old practices and systems were in our way. The mere idea of doing something like this was quite alien to many.
It was a great battle but also a great victory: The quality and speed of documentation improved. We got developers' and integrators' viewpoints included right from the start. The documentation was updated in real-time, and everyone could comment on even the most minor changes. More people shared the information, which improved organizational memory and understanding.
What makes this my fondest coding memory?
This memory is more about a holistic approach and teamwork than coding. We were ten people, and we all fought for this solution. When the battle was won, everyone worked on the documentation, fixing the smallest detail and typo. Until then, documentation had been a lonely job, but a little concrete change made it an essential part of the team culture and a shared project we were proud of.
At Omoroi, we see all parts of software development as interesting and important. In this case fixing the way we wrote documentation improved the teams efficiency and made our lives a lot more enjoyable.