Good documentation is a balancing act. Too much documentation, and it is hard to maintain, hard to find the info you need, hard to complete, and hard to know if it is accurate. Too little documentation, and you have a giant system that is hard to understand and maintain. I find that Airtable’s native dependency checker reduces the amount of documentation that I need.
I have some external documentation on how automations fit in as part of a greater system. However, that documentation mostly states which automations are part of the system and why the automations are setup that way. The documentation does not explain the automation step by step. For a step by step understanding, I think it is best to read the automation configuration directly.
The same goes for documenting scripts. External documentation says that the script exists and why it exists. Any documentation for how the script works is kept in the script itself. I also try to make the code itself readable by using meaningful variable names and functions, to limit the documentation that must be updated.
I have not used AI to maintain documentation. But I’m pretty old-school when it comes to documentation. Most of my documentation is not in Airtable because I like to intermix screenshots and diagrams with text, headings, and links. Airtable does not have a good way of storing this type of unstructured data. Most of my documentation is now in Coda.
