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.
It’s tedious and time-consuming. So it often gets ignored.
In particular, it is crucial for onboarding and as a reference for new hires.
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
Previous Consider adding these attributes for every new model
- Keep track of why decisions were made and features built
This will help you keep track of original reasoning when the feature was built and allow you to see if the circumstances have changed enough to further develop something.
Suggest an improvement to this page (firstname.lastname@example.org)