Help

Documenting Airtable Automations

Topic Labels: Automations
Solved
Jump to Solution
240 3
cancel
Showing results for 
Search instead for 
Did you mean: 
cshenoy86
7 - App Architect
7 - App Architect

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

 

cshenoy
1 Solution

Accepted Solutions
kuovonne
18 - Pluto
18 - Pluto

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.

See Solution in Thread

3 Replies 3
kuovonne
18 - Pluto
18 - Pluto

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.

Looks interesting 

I like it

 

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

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.