Describing and documenting business logic code for non-technical users

[KiraFuruichi]

Background

I recently saw something that sparked a memory for me: I had remembered when I sent some dbt Docs to a business user who wanted to understand how a certain explore in Looker was modeled out. The key chunk of the business logic for this particular model was in a case when statement and this business user (with little technical background) could not understand it, even with column and model descriptions. As data folks, we can often read case when statements or other SQL for business logic relatively easily, but how do we make this easier for non-technical stakeholders?

The question

How do you write documentation for business logic in dbt models that truly explains what's happening in the key areas of the model in a way that end business users can understand? Another way of stating it: When an end business user is sent some dbt Docs on a model to see how certain business logic is implemented, is there a way to write documentation that supports the best readability to non-technical users?

Where I'm at...

I'd love to learn about the best practices around documenting business logic in dbt models. Do you use dbt Docs description? Do you write in-line comments in SQL? A combination of the two? A separate markdown file that provides in-depth business logic context? Eager to hear it all!

[ericalouie]

In an ideal world, the model and column docs should be written as if you were speaking to a "non-SQL-knowing" business stakeholder.

I try to tell my team to write dbt models (with a lot of commentary within the dbt model code) as if you were trying to explain this to someone who's brand new to the Data team.

Then write the model and column documentation as if you were speaking to your embedded team stakeholders. I think this really applies to marts models that touch your visualization layer.

Another noodle -- I think that we haven't leveraged loom videos for documentation enough. Like model walkthroughs for the analytics engineers or thorough explanations of business concept (re: ARR modeling --> change categories) within dbt Docs (model description and column descriptions)

---

NOTE:
In Q2, the Data team is working on documenting our most critical models and templating marts and staging .md files. We're definitely going to touch on this when we start documenting our new entity models 👀

[KiraFuruichi]

Ah this is awesome, thanks Ric! I'm wildly into the idea of Loom videos--think it speaks to a lot of the different ways people are able to digest information.

[brian-gillet]

In my past, we would put decision tree diagrams together in cooperation with the business users or product teams we worked with in the documentation. We found the graphical representation worked for more users than not.

For folks that were less visual learners, we would also include a text description explaining it as if you were talking to the user, similar to what Ric replied.

Ultimately our goal was to build a greater understanding of the field’s logic and more trust in the data element.

[ericalouie]

Yes, Brian! That's how we're thinking about building out our entities as well. Would love to pick your brain sometime on this topic (cc: @dbt-labs/data-team)

[jaypeedevlin]

I think anything is possible here if you're committed to explaining things in enough detail.

Here's an example of a model description which explains some logical decisions made in the process (the columns for this model are similarly detailed):

models:
  - name: agg_daily_subscription_movements
    description: |
      An aggregation model for understanding subscription movements over time, including breakdowns for subscriptions
      that are in a trial vs those that aren't. The model is designed so that all columns (except active subscriptions) can
      be summed to give monthly/yearly numbers.

      Trials in the subscription model are the first portion of select subscriptions. In this model, that first part of the
      subscription is recognized as a separate, `is_in_trial` subscription. If there is a cancellation before the end of the trial,
      it appears as an `is_in_trial` cancellation. If the trial converts to a full subscription (ie is not cancelled before the end
      of the trial), it shows as both a `is_in_trial` cancellation and a `not is_in_trial` subscription.

      Any subscription that is fully refunded is excluded from these counts, as are refunded renewals. Corporate
      subscriptions are also excluded.

      Active subscriptions can be summed for any single day (ie summing both
      values for `is_in_trial`) but summed over multiple days will substantially overreport numbers. Alternate options
      are to take the values for the last day of the period, or otherwise a manual rolling sum of net_subscriptions will
      yield the same value.

      Churn (using [client_name]'s internal formula) can be calculated for any window as
      `cancellations / (cancellations + renewals)`.

[jeremyyeo]

Possibly we now have the problem that if you have to make SQL changes, you now also need to remember to change your "description" accordingly. Potentially with many SQL changes in many different models, you may eventually forget to change a description here or there.

[bbrewington]

I think this is the inherent risk with documentation that isn't auto-generated. In this case if it's info for business users I would think you'd keep it at high enough level to be robust to change in SQL

Valid point, though. Have any ideas for how to prevent the two getting out of sync?