Hi all, I work at an a nonprofit (of ~15 people) who uses Airtable extensively, for more and more processes within our organization. This all has occurred relatively organically. I was originally driving it, even though it wasn’t part of my official role, but it’s now embedded in our organization beyond me. We even have a couple of other staff members building out complex new bases that impact the team.
Our biggest challenge right now is that we don’t have sufficient documentation - not for the end user and definitely not for the back-end automations, etc. We also need clearer documentation to support consistent data use for reporting, etc. (Right now way too much is dependent on me.)
I am now spearheading a project to do all of this, but this is definitely not my forte. Does anyone have guidelines or approaches to documenting Airtable bases and processes that they think work really well?
I know this is a broad question, but there is so much expertise and creativity here. I’m mostly interested in how people approach documentation generally*, if there are key lessons you’ve learned about what does and doesn’t work, and if there are ways you’ve found to organize your documentation that you would recommend.
*I struggle with documentation generally, but it feels especially difficult when our use of Airtable is constantly evolving and deepening. Even on our most “mature” base, I’m still getting feedback and making adjustments.
I don’t have any specific expertise or advice to share in this area, but I have heard great things about Scribe, which is a tool that makes it easier to create documentation:
I always find documentation challenging. It’s a big issue for me, especially when working on reasonably complex sites with Airtable, Fillout Forms, Make or Zapier, and sometimes eSignatures.io. Tracking workflows and dependencies can be quite complicated.
Tango is a helpful tool I use. It provides clips and instructions while automatically following my cursor, which is great for certain tasks.
Additionally, I sometimes create videos on Loom for myself or others.
However, sometimes, writing documentation distracts me from coding or databases. I found AudioPen, a simple AI transcription service. It’s perfect for keeping track of my thoughts during the process.
When I need to remember what I’m doing at a specific point, particularly if I have to pause the work overnight or step out, AudioPen is the best way to stay connected to my coding without losing focus. If I write things down, it takes me out of the zone.
These are my three imperfect methods for handling documentation. If anyone has a more refined or effective approach, I’d love to hear about it!
Tango and Audiopen have free versions, which work well.
I have affiliate links for both - so please use them - I will get the affiliate fee if you decide to upgrade
Thank you both! I’m excited to check out these tools.
@Seamus I definitely have the same issues. I’ll try AudioPen because I often feel like my work on Airtable-related projects are all or nothing. I hate to stop a project because I’m so immersed in the details and know it will be hard to jump back in.
Also, while the creation of documentation is painful and these are all quite helpful, I am also wondering about practices to organize documentation so it’s accessible and found when needed? (Sometimes the issue is to even make sure people know they should be checking document!)
One of the issues with documentation is that inaccurate documentation is sometimes worse than no documentation. With evolving systems, it is very easy for documentation to get out of date. So, when deciding what to document and how to document it, keep maintenance in mind.
Here are some guidelines I use
If something can be figured out easily be “reading” the system, I don’t add additional documentation. For end user’s this means documenting where they need to go to start the workflow, and then having interface pages be as intuitive as possible to avoid needing additional documentation. For back-end things, this means that I try to make the system easy to read with clear names and straightforward logic in automations, formulas, and scripts so that they need minimal additional documentation.
When it comes to maintaining documentation, plain text is the easiest to update, followed by images, followed by video. My images tend to be mostly screen captures and other diagrams. I rarely use fancy graphics. When things change, it is much easier to change a few words and drop in a new screen shot versus recording and editing and new video.
Include updating documentation as a task for any projects that involve making system changes.
Add a date-stamp for any documentation that needs to be manually maintained. By comparing the documentation date-stamp with when we made changes, it is much easier to tell if documentation didn’t get updated when the changes were made. I find that this date-stamp also needs to be manually maintained, so that minor changes like fixing typos don’t get mistaken for major updates.
Don’t try creating all the missing documentation all at once. Create it piecemeal as you have time and opportunity.
Decide how you want to deal with versioning of documentation. Do you need to track previous versions of the documentation? Do you want a change-log? Or is simply documenting the current state good enough?
For user documentation, it is fairly easy to document how to do a thing. However, the “how” is often easy to figure out. Don’t forget to document “why” to do the thing, “when” to do it, and how to pick “which” thing to do.
Currently, yes, Coda is the main place where I document Airtable systems. I do use other tools for creating media (screen shots, diagrams, animated gifs, etc.), which I then dump into Coda.