Writing good docs can be tedious and time-consuming

In my experience, it is painful to enforce discipline to continue doing it, unless getting explicitly paid to do so – such as on a project for an external client.

As a result, it almost always eventually falls by the wayside.

But it becomes more important as your team and product grow

It is crucial for onboarding and as a reference for stable features that might be rarely modified.

Give docs the respect they deserve

The best way to write docs would be to stay disciplined and make writing documentation a step in the development lifecycle.

Done would be defined as “Shipped and is documented”.

If you can do that, well done. Please get in touch and tell me how you did it and what tools you used, because I couldn’t so did everything but.

Or don’t, and instead, write code to be read

You don’t need to take it as far as literate programming having the prose take center-stage with code just peppered in.

But, you should ensure that code is always written to be read.

Rubocop has several rules that help including naming and style.

Use your editors documentation features

For particularly hairy things, use your editor’s documentation features.

It works well on RubyMine with popups showing an explanation of the method and the parameters.

If I recall correctly, VS code works similarly.

Post detailed comments on tickets and pull requests

Code can be quite self-explanatory when looking for how, but the original tickets or pull requests should contain the why. That makes detailed comments and an excellent source of documentation.

Even if a discussion happened outside of the tool you use, still post a comment that summarizes the conclusions.

And generate as much documentation as possible automatically

Many tools can generate quite a bit of it. Below are some Rails-specific suggestions.

Database schema

Annotate models

Instead of desc on the database, there is a gem that annotates models with column names.

The output looks like this:

It can also do routes, although, I’ve found that too messy.

Azimutt

You can also switch to using structure.sql instead of schema.rb and use a database explorer such as Azimutt to generate ERDs.

API

If you use the grape gem, there is grape-swagger, a gem that automatically generates swagger.json from the API definition.

Since it’s generated directly from the methods defined in the source, it is 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: