First Aid Documentation

When we work on any project, we(developers) love to design architectures, implement algorithms, optimize stuff, load tests.. etc. We have so much practice about how to beat these challenges. As a team, we could easily discuss/talk about any development lifecycle step days and days. But when it comes to documentation, every practice becomes obsolete and we mostly try to run away from it. Right?

In our Indexing Offer team, we have very challenging scales on runtime environments. In summary, we collect 40+ different event types from 6 different teams to invalidate over 300 million invalidations per day for 260M+ content.

With these challenges, we empower our technical muscles in time and we could be able to handle the problems with our “engineering instincts”. While our system is growing dramatically, we create more knowledge that should be propagated among teams and our members.

Also, runtime usages are not the only thing that challenges us. Last year, our 9-member Indexing PDP team split into 3 different teams with 21 members. While our teams are growing, every new member has to know a bunch of new technologies and learn about our domains. Even though we try to simplify our environment, this complexity is making our onboarding time longer.

In the early weeks, our new developers mostly lost their way, while searching for which tool/environment they need to look at. Even if they understood the tools, finding the right link could be exhausting. Our services work in several environments and these environments could have their own monitoring, logging, and tracing tool instances. Also, this service could have integration with an automation test tool, security check tool, quality check tool, database, queues, etc. With these long lists, links could easily be friction points for every developer.

Power of Readme

To solve this problem, we try to use the power of Readme files and collect all related needs in one document. In a simple way, developers could easily find all dependencies when they are coding on a new project. Also, we create a Readme template for spreading common sense. The first part of our Readme template includes related links that look like the below image.

We also have processes for every service we need to be implemented. Therefore, we add a checklist on Readme and follow it while developing.

After a while, our team noticed adding a sample payload is useful for local testing. Moreover, some of our services also have INSTALL.md to prepare the development environment.

It is not TL/DR. But,

With the power of the Readme file, we

• leverage our onboarding times,
• follow our progress on every service level,
• simplify local testing and development environment installations.

If you like to think beyond development with us, you could apply for our open positions.