Write as if the reader never attended design meetings, never read the implementation tickets, or even never used the feature. The goal is to make them productive fast.

What to include:

1. What the feature does, its benefits and the problems it addresses

2. How to use it locally

• application settings to enable

• if any third-party service is required, how to set it up and get its credentials

• data to create or seed

• exact steps to follow to use the feature

• expected results

This section is critical. Developers often spend more time figuring out how to use a feature than fixing the bug itself.

3. How it is designed and how it works

Describe the architecture and the reasoning behind it:

• key components and data flow

• links to important classes, modules, and methods

• trade-offs, rejected alternatives, known limitations

4. Troubleshooting

Provide a practical playbook:

• typical symptoms

• likely causes: internal services, external APIs, configuration issues, end-users misunderstandings...

• logs to check and where to find them

• relevant metrics and dashboards

• concrete steps to confirm and fix

5. Maintenance

Document recurring tasks:

• upgrades (libraries, services, dependencies)

• checks to perform after upgrades

• anything that requires periodic attention

6. References

Link to useful resources:

• external APIs

• original design documents

• related tickets, tests, diagrams, specs

and link to the doc from the relevant pieces of code to make it more discoverable.

Finally, treat documentation as code: keep it in the repository, version it, and review it in every PR. This "Docs-as-Code" approach prevents knowledge rot and provides AI tools with the context they need to better support development.

Take this example: your application allows users to copy a product. Some associations should be copied (like category mappings), while others should not (like customer comments).

class Product < ApplicationRecord
  has_many :category_mappings, dependent: :destroy
  has_many :customer_comments, dependent: :destroy


  def copy
    Product.transaction do
      copy = dup.save!

      category_mappings.find_each do |mapping|
        copy.category_mappings.create!(mapping.attributes.except('id', 'product_id', 'created_at', 'updated_at'))
      end

      copy
    end
  end
end

When implementing such a feature, you'll review each existing association and decide whether it should be copied. But when a new association is added later, it’s easy to forget to update the copy logic.

You can prevent this by adding a meta-test that fails whenever a new association hasn’t been explicitly accounted for:

require "test_helper"

class ProductTest < ActiveSupport::TestCase
  test "all associations have been accounted for in copy logic" do
    accounted_associations = %i[category_mappings customer_comments]
    unaccounted_associations = Product.reflect_on_all_associations.map(&:name) - accounted_associations

    assert unaccounted_associations.empty?,
      "Please account whether these associations should be included in Product#copy \
       and then add them to the accounted_associations variable of this test: 
       #{unaccounted_associations.join(', ')}"
  end
end

Now, if someone adds for example has_many :variants to Product without updating the test, it fails, reminding them to make an intentional decision.

This pattern applies anywhere you maintain an explicit list of elements that define behavior.

For instance, you can add similar tests to ensure all attributes or states are consciously handled:

• API exposure: every attribute of a model is either exposed or explicitly hidden

• Audit logging: every field change that matters is intentionally logged

• Exports: CSV or JSON exports always include all relevant fields