How to Easily Document Your Integrations Using Notion

As the workflow automation market grows, new eventualities and situations begin to emerge.

Among these, there is the process of documenting integrations and automations, which many (if not most) companies will need to address in the foreseeable future.

Anyone who has dived into tools like Make knows that building one automation often leads to building many more, and here’s where the main problem pops up:

How do you keep integrations organized and documented?

Finding new ways to improve efficiency and automate tedious tasks is a great thing. However, as the number of integrations increases it’s fairly normal to lose track of them and know what each one does.

In this line, it’s important to implement and maintain a documentation system for your automation portfolio as it expands.

This is particularly relevant for companies that automate extensively, but also for agencies and tech consulting firms that build integrations for multiple clients.

So, what’s the best way to document integrations?

In order to get real-life answers and examples, we asked certified Make partner XRay.Tech about how they manage documentation for their clients and themselves.

Let’s take a look at what they shared with us.

A stepping stone to automation at scale

XRay.Tech is an automation consulting company based out of East Haven, Connecticut. They currently manage hundreds of automated workflows for their customers, and to control their own internal operations.

To do this, they created a documentation method that makes it easy to keep track of every app integration they have developed, touching upon workflow performance as well.

The key element of it is a rising star in the app world: Notion.

If you’re building integrations for your business or for clients, we encourage you to follow along and set up a similar system for yourself.

Dude, where’s my integration?

Thorough documentation is just as important in the low-code and no-code automation worlds as it is in traditional software development.

In essence, the main goal of documenting your integrations is the same as documenting code: You want to make sure that your colleagues understand your work and contribute to it without extra friction.

XRay’s tool of choice to achieve this is Notion.

While you could use other apps for documentation, XRay leans on Notion’s versatile features to manage an extensive collection of information.

For instance, Notion lets you add custom attributes to any document to help you sort and organize all of your information. You can add people to the document to:

• Make clear who should contribute to it

• Associate it with a client, project, or tasks

• Attach helpful links and files to give further context

This said, you can also apply the general principles of this documentation method to any note-taking app or word processor, but the examples below rely on Notion.

Let’s take a look at them.

Documenting integrations: First steps

XRay’s documentation process begins with a brief but descriptive summary of what the automated workflow does and how it works.

A good tip to maintain consistency at this stage is to imagine that someone who has never seen these integrations will be reading the documentation to learn about them.

With this in mind, make sure to include enough information so the reader can understand the purpose of the workflow, as well as each of the tasks that compose it.

XRay typically creates a Notion page for each process, which in turn can include several workflows that contribute to its functioning and fulfillment.

Depending on the amount and complexity of workflows involved in any given process, subpages for each workflow can be created as well (point for Notion’s page nesting capabilities).

To keep record uniformity, a documentation template that prefills each Notion page with a few prompts is employed.

In the screenshot below you can see how a blank, newly-created template looks like.

As you can see, the template contains pre-defined questions about when and why the automation is used. These are instrumental in clarifying its use case.

On the other hand, questions about the data involved help outline the technical setup of the workflow and the apps involved in it.

Screenshots of the workflows are also included. This is a convenient way to visualize the integration without needing to create a new graphic from scratch.

Next: Adding attributes to organize the documentation

Notion allows you to add a wide variety of attributes to each page, and this is one of the reasons why it’s such a great tool for internal documentation.

For example, you can create status notes for each workflow, define its type, add a link to Make (where the automations are hosted), list the contributors, and link the page to a client profile (or mark it as an internal automation). See the example below for reference:

You can then use Notion views to sort the data based on the aforementioned attributes.

This will allow you to see and analyze all your workflows on one screen. For instance, you will be able to see which ones were made for internal use, those that are under construction, or combine other criteria to get an accurate sense of workflow status, purpose, and type.

In the case of XRay, these flexible attributes and views help employees find the integrations they’re interested in and quickly study all the available information.

It’s worth noting that these are all custom attributes and that they can be changed to suit your organization’s needs in minutes.

Conclusion

When you are starting out with automation, it isn’t too difficult to keep tabs on Make scenarios, but that situation can change as you build over time.

For those companies dealing with a growing number of integrations, it will become vital to have a system for explaining what they do to others.

Implementing a documentation system early on will facilitate automation at scale by keeping everyone on the same page; in addition, it’s a good way to avoid the dreaded information silos.

The main take here is to keep an eye on how you document integrations and automations.

As our friends at XRay Tech showed us, creating a simple, informative system will allow you to replicate useful workflows in a matter of seconds, and avoid all sorts of redundancies.

In a similar manner to what happens with automation itself, greater efficiency awaits with its documentation.

Happy automating!