Photo by C M on Unsplash

Why syncing docs matters

One way sync or a two way sync, you may need it

Christiaan Huizer
9 min readMay 31, 2023

--

One task one doc

In an remarkable contribution,

employee Al Chen wrote:

These days, I try to have my templates do one thing and one thing well.

Let me rephrase this to one task, one doc.

Late 2022 I described how complexity can turn against you easily. Since then we have descriptions in the columns and we can comment in our code editor. Two important steps helping us to keep oversight. The third request — the link between tables and columns living in other tables — remains however unclear.

Rickard Abraham wrote:

I often find myself clicking delete on a column simply to figure out What is this column even connected to? Oh, right!

His contribution to solve this issue, although interesting is not my cup of tea. I am convinced

should solve this natively and as long as the company won’t do this, it shares implicitly that solving this kind of complexity is not yet important to them. Maybe it is the way of saying: Keep It Simple Stupid.

Simple means one task per doc like all core employee data and not mixing this — in the same doc — with sick leave for example or a car policy, budget exercises etc. These tasks have their own doc in this ‘one taks, one doc’ approach. This brings us to the importance of linking data between docs. You need the employees in your doc about sick leave or in your docs about budgets and maybe you want a doc that has budgets for innovation, budgets for sick leave etc.

Sync your data wisely

I am not a fan of the current Cross Doc logic for reasons you find in my blog below. We need a more flexible and faster approach that can easily be filtered.

The alternative I promote for the moment is based on webhook logic. In the long term I would love to see a native

solution, which has been announced by the way. To succeed needs to break the permission logic between the source & target doc. The big question is: can they make it work? To relate data in docs, we need one way communication and sometimes we need a 2 Way Sync. And we need something on top!

We need humans

When you bring in data from another doc via a webhook triggered automation, you make changes in the receiving doc in well defined table. You can push buttons in the receiving table and thus update data living in this doc in different tables, thus not only in the table the webhook ‘talks to’.

You can trigger a calculation based on the value you bring in.

What you cannot do is trigger a new automation via for example a row change in an other table that is the result of an earlier bot driven action. It won’t work.

Bots don’t trigger bots, humans do.

One & two way sync only works when a human edits a value directly or via pushing a button. This is an important observation, it excludes practices that move data through several tables before sending it back to another table based on row change. The row change as a result of an automation does not trigger any other automation.

Simplicity is key

When we launched our paid two way sync solution, we observed in our own dealing how easily we got lost in the system we created. To avoid wandering around through pages, tables and automations we simplified the sync logic by stepping away from buttons. The new fully automated sync is easier to understand and to maintain. We also worked on the order of things. Applying this procedure prepares for speed:

  • Name is not used in the automation, only as object in the table
  • column1 = unique identifier per row
  • column2 = checkbox to check or uncheck in case of deleting
  • column3 = button to delete rows on both sides

Although it is not required to use the deletion logic, we understood that keeping this pattern promotes progression. We want to keep our contribution simple for us and our clients. There is already enough complexity in the

realm. Simplicity requires a profound and not a superficial understanding of the matter at hand.

Simplicity in Coda Killed — SICK

Certainly makers impressed by their recent understanding of a concept tend to communicate this concept as (very) difficult, not for beginners, etc. When this happens, the quality of the proposed solution is often inversely proportional to the expectation created. Below an example

One of the most advanced

workflows you can create is a 2-way live editable sync between tables I show you how to do it step-by-step in this guide WARNING: Not for beginning users.

I know a bit about two way sync and I can assure that the promoted approach is a recipe for trouble to the extend that you wish you would have never met this particular maker.

I am intrigued by both observations in the above tweet. I have a master in philosophy and do remember very wel attempts more related to showing off than adding value. Today I make a living as

Consultant, which resembles more the engineering part. I am happy when my readers tell me that what I write is simple. Maybe not all my writings, but I believe most of them.

feedback from a follower

When dealing with concepts as two way sync, I am convinced it is better to think twice before sharing, allowing yourself to see through, polish and promote only when you found some edge cases that did not break your base logic.

Two levels of difficulty (not complexity)

In a previous blog I wrote about how difficult is different from complex.

Complex does not equal difficult. Complexity implies many interactions going on at the same time and you have to keep track of them in a certain order to keep the proces going. Multiple automations and tables with many columns stuffed with formulas generate complexity.

In

, operations can get difficult on two levels. First writing the formulas and second the data architecture. Since we can develop fast in we tend to forget a bit about the latter and we start coding. This will turn against you sooner than later and often you won’t see it coming. Your lack of foresight will catch you by surprise.

Mostly when I develop a solution, the first version is not the best and I put it aside for a while. After some time, I polish and improve. Sometimes it gets shorter, sometimes a bit longer to be a better compagnon de route for my future self. It is mainly in my second round I add comments to my code and I do so by answering the questions of my present self.

Second there is an aesthetical component which is harder to explain. Elegant solutions are orderly and as a result understood fast even when the concept is difficult. Applying proved patterns pays back. Next repeat patterns and adapt. Well written code needs little explanation and no warnings. Even a beginner notices the logic, although she may not directly be able to reproduce it, but that will come over time.

As said before, simplicity is not only about formulas, also about the data architecture and this correlates to: one doc, one task.

One task per doc and the art of syncing

Once we agree that we attribute one major task per doc, we won’t get far when we don’t connect docs properly. As explained elsewhere, webhook based solutions to create one way and two way sync are the way forward as long as

does not solve the issus we face today.

The major issue is that for example you have a doc for your client that gets data from a doc “all clients” and the client has only edit and write access to her doc not to the source doc. The moment

allows this sort of set up with two way sync and without the 10K limitation on row, we are getting somewhere.

That having said, we should understand that relating docs increases the complexity on various levels. This complexity you can only limit by defining clearly how the docs relate and how the tables and the functions in the doc are related.

Tips to lower the level of complexity

There are a few things you can do to reduce, but not take away all complexity:

  • Proper naming of tables, columns and automations. I apply the camelCase convention and I avoid column names that equal function names like Date. Instead I write theDate, likewise I write theDuration.
  • Use descriptions in the columns to explain why this column is required and what it does. For automations this is not yet possible, but it would be a relief to have descriptions there as well.
  • Limit the columns per table. When I read about 40 and more columns per table I always wonder why makers need this? To split calculations? I don’t know, but the less columns the better. In you add rows when you add data, not columns.
  • Rows you can reference when building up your automations containing URLs and tokens
  • Define the sync logic in your automations. Thus not via buttons in your tables. You want all logic together to keep an overview and you want fast interactions (buttons in tables slow down).
  • Hide (sub) pages you only need occasionally. Put tables you need out of view in the canvas column in a table and set a filter on that table referencing users (but don’t expect this to be a safe option). Data not required to be shown on the screen does not ask for a lot of processing power, it speeds up your doc.
  • In case you have a general doc (like all employees) you have the choice to push all employees and delete the rows you don’t need in the target doc. The alternative is you set a filter in the source doc before pushing. The first option permits you to deal with an expiration logic (also in case of products, procedures, loans, tarifs, etc) and seems therefore more suitable to me.
  • Design a doc schema. This is a set up in which you define per doc the main task and supporting sub tasks. Once you have this put in order, you can start building the core docs feeding the specific docs.

Building your own sync based solution

In the blog below I showed how to put buttons in tables to set up a one way sync. Not because this is the best way forward, but the easiest to understand for anyone new to this sort of solutions. From here you move forward to full blown automations and you will enjoy the building process. However, the day

meets our criteria for a mature 2 way sync, we start using the native solution and we can put this solution away. However I am afraid we will need this solution for a long, long time.

My name is Christiaan and I support SMB with calculations (budgets and — Human Resource — planning) and I prefer using Coda to get the job done. More about me below:

I hope you enjoyed this article. If you have questions feel free to reach out. Though this article is for free, my work (including advice) won’t be, but there is always room for a chat to see what can be done. You find my (for free) contributions to the Coda Community and on Twitter.

Coda comes with a set of building blocks ー like pages for infinite depth, tables that talk to each other, and buttons that take action inside or outside your doc ーso anyone can make a doc as powerful as an app (source).

Not to forget: the Coda Community provides great insights for free once you add a sample doc.

--

--

Christiaan Huizer

I write about how to Coda . You find blogs for beginners and experienced makers. I publish about 1 / week. Welcome!