Making Sure Your App Isn't a Black Box

By Jeff Gilson posted 10-29-2019 09:25

Have you ever taken over an app from someone else? It all starts out fine, but then you make a change and everything breaks. Well, don't worry, it's not just you. More to the point, it's not your fault. (It may be a little your fault, but I'm not here to assign blame.)

Chances are good that the app you're working on doesn't have the documentation that will make it future-admin-proof. However, that can be fixed, and I'm here to show you how.

Un-building a Mystery

Virtually every part of a Quick Base app has places for documentation. If you go to your home dashboard and click the settings icon, right there on the app settings page you'll see a big "Description" box at the top. That box is there for each of the tables as well. This is a great spot to put general information regarding the structure of the app, and the purpose of each table. You don't need to put a whole manual there, you're just looking to send future admins down the right path.

Image shows the description field on the app settings page

Fields, when you're looking at their settings, each have "Comments" tabs, and on that tab, you can spell out what this field is used for, and relationships it has with other fields (for instance, formula fields where it's used).

Image shows a comment box in a field's settings
Other spots with a Description field include reports, automations, Quick Base actions, and user roles. You want to keep these as concise as they can be without leaving out necessary details.


One thing to keep in mind is that sometimes people aren't going to get down to the comments and descriptions before trying to make a change. This is where having consistent naming (and for larger apps, naming conventions) will be a huge help.

If you have Purchase Orders in one table, referring to the same items as Invoices in another will be confusing for someone at some point. On the other hand, if they are truly different things in your work flow, make sure that they have comments and descriptions to explain the difference. Make sure that assumptions can't override your intentions.

Comment Chameleon

One of the most effective and least used features is the ability to put comments in formulas. This is especially useful for long formulas with many parts. Adding comments is as simple as starting a new line with "//" (without the quotes).

Image shows a formula box with comments at the bottom
You can add the comments at the end of lines, too. The only rule with comments is that after the // the only text is comment, and to continue the formula, you need to hit enter to get the next line.

Bottom Line

All of these tools will help your business down the line. This way, once you get that big promotion, the person taking your place won't have to stare at your app and hear "Sound of Silence" playing. It's a win for everyone.



11-04-2019 12:19

An ERD is essential.  The native Quick Base Relationship Diagram tool is not effective yet for large applications.   The ability to see clearly cascading down parent child helps explain a great deal.