Documenting Airtable Automations

[cshenoy86]

Hello airtable enthusiasts,

I was wondering if anyone here has tried documenting airtable automations. I have a bunch of automations that use airtable blocks and sometimes even use the airtable scripts. I want to do a step by step documentation of what the the script does in a separate file for future reference. Is it possible using airtable? Alternatively does airtable AI help with it? If not, are there any other tools that help with the documentation process?

Thanks

[kuovonne · Accepted solution]

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.

[nick_solunin]

Looks interesting 

I like it

how do you organize your documentation ecosystem in Coda? How to you keep it updated here? 

[kuovonne]

For me, keeping documentation updated is a manual process. When I change things, I have to manually update the documentation. This is why I try to avoid documenting anything that can be easily determined by looking at the system directly.

If a standalone base needs documentation, I give it its own Coda doc. I do not have a specific structure—I use whatever feels right for the situation. I have pages for complex sub-systems within the base and use Mermaid diagrams to show the relationships between relevant tables. I put in links to related automations and interface pages. If the relevant editable fields are many layers of formulas and rollups away from the final calculated value acted upon, I list the source fields, but do not document the intermediate formulas. 

[kevink]

Hi, is there anything you can share about AI automation? Some things work great, and others I've had a hard time working around, such as AI-generated content being added to Google Docs. I've struggled a bit with the new functionality.

FYI, We tend to do Looms for most everything, including automations and database architecture. We then have a table in Airtable with links to each of these Looms. Anything not in a Loom is in Google Docs/Sheets and linked from AIrtable as well. Just to keep everything in one place.

[jillmonterey]

I don't consider this solved. I've built a base for people with very little understanding of Airtable. The Descriptions I've provided for the automations and fields might be meaningful for more sophisticated users, but even they can't tell the entire story because the lookup tables need a manual refresh every 2 months as my company changes its product offerings. 

There's an extension called "Description" that allows you to add something like documentation to your base, but it doesn't allow you to include graphics, which means no screenshots. Same limitation when adding a Text element to a blank interface.

I've created a Maintenance Guide that I'd like to add to the base. My workaround has been to create a table called "Documentation" in which I have two fields, "Title" and "File," and I've added the Maintenance Guide as an attachment to the "File" field. 

I'd like to see an actual Documentation Interface or other way of storing documentation in the base.