Link Search Menu Expand Document

The more documentation you can generate automatically, the better

Docs are useful but will quickly take a back seat. Using tools that generate as much documentation as possible automatically are essential.

Writing good documentation is not a priority

It’s tedious and time-consuming. So it often gets ignored.

But it becomes important as your team grows

In particular, it is crucial for onboarding and as a reference for new hires.

So, make use of tools that generate as much of it as possible

I realized that I was using desc a lot in the beginning. So, I found a gem that annotates models with column names.

The output looks like this:

Similarly, when I started working on the API, I found a gem that automatically generates swagger.json from the API definition. That means it was also always up to date and accurate. Next, I found a tool that took in a swagger.json as input and converted it to a presentable format. The result of these two steps looks like this:

You must also remember that code must be written so that it’s easy to read. Prefer variable names such as order_items_total_weight instead of tw.

Related Lessons


Suggest an improvement to this page (me@ognjen.io)