The ultimate Make Documentation Topic

There’s a suggestion in the idea exchange for better Make docs, but there is very little specific and actionable recommendations in the request.

Let’s use this thread to make specific and constructive documentation suggestions. User interface docs are welcome here too!

Rationale

Many look for a tool like Make when they want to save time and money when performing repetitive software and data tasks. In many organizations and businesses, business processes and workflows usually take place with Microsoft Office or Google docs strewn about the office, archived in a shared folder. Or worse, these processes are just passed down by “oral” tradition in companies. Today, there are software services and apps like Make that enable the design and configuration of automated data workflows. This is a huge win for automating more repeatable business processes and for getting things done quickly, accurately and efficiently! This is the true value proposition of no/low-code tools: concretizing workflows.

But In order to wield the power of Make, business process automators will need to make sure they improve their logical skills and data capabilities before fully mastering automation. Users with any programming or data management experience will have a clear advantage when using Make. These are the first users that will convert to paid customers and continue to lever Make for a long time and tell others about it. But to really change the business automation world, non-technical users will also need to level up their data and logic skills.

Make is categorized as a “no-code” platform, and while there may be very little code when using Make, a logical, data-driven mindset is an absolute must. Building and testing scenarios in a “start small” and iterative approach must also be documented and described. Integromat documentation should encourage and never downplay “willing-to-experiment” thinking.

I propose these 3 principles for Make documentation:

  • No assumption of any prior knowledge of programming, logic design or data structure knowledge
  • Liberal use of rich media (text, hyperlinks, images, video and audio where appropriate) and documentation structure including deep hyperlinking between documents
  • Clear scenario examples that are downloadable

The style of the documentation must use plain-language whenever possible. The use of plain language ensures the reader understands the documentation as quickly and completely as possible. Plain language strives to be easy to read, understand, and use.

Do NOT ever ever do this in documentation

This is very, very lazy and unhelpful:

Inspiration

Style Guides

https://www.writethedocs.org/guide

Reference documentation systems for inspiration:

This Parabola foundation doc must be created and maintained for Make. They set the context for effective usage of Make.

Another great piece of documentation:

These beginner, intermediate, advanced workflow tutorials are excellent.

Platform overview

Reference docs needing updates:

https://www.integromat.com/en/blog/zapier-vs-integromat/

3 Likes

Release notes

Did you know the Make docs have had release notes since April 2022? Here they are:

https://www.make.com/en/help/about-make/release-notes

These are fine but I believe they need more detailed screen shots and always an example of usage with links back to up to date docs.

Fire Explosion GIF

The basics need restatement.

What is Make

Make is a software platform of tools, apps and resources that helps automate the flow of data between one or more web apps. Make has a highly visual and intuitive user interface to design automations, also known as “scenarios.” Make enables growth through connection: the value of Integromat comes not only from its own features, but from its ability to connect external tools, teams, data, and processes. You can think of make as a replacement for repetitive “copy and paste” operations you may make when manually moving data between documents and various screens in your web services and apps. Make runs on secure servers in the cloud, but it can be licensed for on premise use and embedded in your own applications.

Who uses Make?

Make can be used by anyone. You don’t have to be an experienced developer or data scientist to lever the power of automation. A sure sign to know Make can be used: when you or your team repeatedly do something over and over manually. Another sure sign for the needs for automation is when a service you are using is limited in functionality, and you wish to “workaround” or improve the functionality of one or more services. Stitching services together with Make is very useful!

The Office Monday GIF by 20th Century Fox Home Entertainment

  • Managers can increase the productivity of their team by assembling workflows that are commonly performed but slow down your team. You can reduce friction in processes where multiple people have to be involved to accomplish a task.

Make It Rain Money GIF by Jasmine Star

  • Sales and Marketing teams can automate a lot of their repetitive work when creating or reusing sales and marketing content. Marketing automation at scale can be built tailored to the needs and services already in use by marketing staff so there is no need to learn new systems or migrate away from what you already have. Sales staff can reduce the friction from prospect to deal close by automating the collection of data, qualification, proposal generating and contract signing.

office space stapler GIF by 20th Century Fox Home Entertainment

  • Finance and accounting staff can create automation to collect, assemble and route data and documents between systems to accelerate the speed of reporting and reduce friction in management of cash flow and bookkeeping.

  • Project and service management can improve service delivery and common project management processes. Project optimization can be achieved by breaking down bottlenecks in knowledge transfer and data delivery.

stupid youtube GIF

  • Executives can create strategic advantage in their organization by building a culture of digital transformation, saving time and money while becoming more profitable.

revenge of the nerds 80s GIF

  • Automation consultants can build businesses helping companies of all sizes take advantage of the power of automation. They can create reusable automation solutions prepackaged for use across various vertical markets and audiences.

Charles Dickens Money GIF by INTO ACTION

  • Families and children can automate their homes by triggering common automation scenarios and activating IoT devices to help make lives easier and more fun!

APIs and Make Apps

Make enables visual programming of documented Application Programming Interfaces (APIs) published by each app vendor. APIs allow two software applications to communicate with one another. For example, when you use an Facebook app on your phone, or send a text message through Whats App, or check the score of a football game, APIs are used by the apps to send and receive data that is displayed by each app.

You can think of an API as a mechanism to retrieve or send data between apps. Many functions and features of an app can also be invoked through the app’s API. For example, watching a Dropbox folder for changes can be done with code using the Dropbox API. Most APIs are built for use by developers only. But with Integromat, using the Dropbox API can be done without writing a single line of code:

Download Integration Dropbox Blueprint

This module will watch new files put into the /Zoom folder on the dropbox owned by alex@newpathconsulting.com. A Dropbox connection for Integromat can be created with just a few clicks using the Add button.

Once this scenario is set to run, any changes to the /Zoom folder will return information about the changes, stored in an Integromat “bundle”. The Watch Files module in Integromat can also be scheduled to run on a schedule to monitor for changes to this folder. Once the scenario is run manually or on a schedule, if the module finds a changed file or folder the following “output bundle” is shown:

The keys in the bundle like “Tag” and “Name” and the values like “file” and “Integration Dropbox.json” in Bundle 1 are described directly in the Dropbox API. The output bundle keys and values can (and should) be used in other parts of the scenario as input to other app modules.

To illustrate the capabilities of a Make app and its modules, let’s look at the Dropbox app in Make. The Dropbox app functionality directly depends on the underlying service’s published API. Here is the Dropbox API explorer, made available by Dropbox. The “get” API call retrieves a file from Dropbox, after authentication is made.

Note that web API requests are usually made on the Internet with HTTP, much like any web browser request you have ever made by clicking on a link. The explorer above shows you the communication details behind each API request. If you want to learn more, read about Web APIs, the technology used to communicate between all apps.

The important take away: Make abstracts away most of the API complexity for you.

Interpreter Translate GIF by Panama Translator

The API “get” endpoint above is used in Integromat with the Dropbox app. One key benefit of Make is that this simple interface authenticates and communicates with the Dropbox API, which makes it easy for non-developers to become just as productive as many developers.

The Dropbox module to “Download a file” is the implementation of the Dropbox “get a file” API call above:

It is important to understand that an API and all its functions are designed, maintained and tested by the app developer (eg Dropbox, Google, Salesforce etc). That means that all APIs have a natural constraint on what Make scenarios can do. Make scenarios can do a lot, but they are limited to what an app API provides in terms of functionality. For example some APIs allow you to read data, but not update or create data in the app. As a result the Make app will also be only ever be able to read data, until the app vendor updates the app to support creation and updating of data. The best APIs include a generous number of “API end points” that can then be designed into Make apps and used in many scenarios.

Make apps are created and maintained usually by app vendors using the Make app software development kit (SDK). In most cases Make writes and maintains the apps and modules for popular online apps. The scope and usefulness of Make apps is completely reliant on 2 factors:

  • the API features and functions provided by the app vendor
  • the Make app capability created based on the available vendor’s API

Rock On Reaction GIF

WebHooks and Make Apps

Im Out Walking Away GIF

Webhooks are another way that apps can send data to Make. Make can send outgoing Webhooks using the HTTP app. Webhooks do not depend on an API, but are usually built into web apps as a mechanism to send data out to another app. Webhooks are simple, do not carry “state”, and are usually called in real-time.

Webhooks must be supported from the app sending data. Webhooks don’t need to be monitored or polled and can be invoked at any time. To allow Make to receive data from an app via a webhook, Make webhooks must be created and can be used to pass structured data using an ordinary HTTP request from an app or service into a Make scenario. Webhooks can also be used to send data between scenarios.

One interesting thing about webhooks is that even apps that don’t have an API can implement webhooks to send information to Integromat based on certain events. A webhook can be sent on a new customer being added, a new invoice being created, or a file being updated. It is completely up to the app vendor to specify when webhooks “fire”. In any case a Make webhook can receive this data and take action, using the structured data that is passed into Make. This is a very powerful, low-effort technique that can be used to connect apps to Make and to connect Make scenarios.

Make Important Words

Care Bears Otherkin GIF

There is a published glossary of Make terms. It is important not to replace these terms with alternative terms, to avoid confusion.

Scenario design Best Practices

Happy Jim Carrey GIF

  • start small
  • test pieces
  • assemble
  • break down
  • test with filters on routes

Common challenges

Fail Empire Strikes Back GIF by Star Wars

One quick thing

before i come back with my standard wall of text when I have more time. :rofl:

I really like what n8n does with their embedded flows in their community up to now they do not have it in their documentation, but it might make the documentation both more maintainable and user accessible.

Don’t know if “scenario” embeds are realistically achievable with :make: make though in the near future.

1 Like

Internal Limitations of Make.com

There are several (currently undocumented) limitations in Make:

  • the User Interface (UI) does not let you process more than 3200 bundles in one call. Use paging or filtering, if available, in the API.

  • maximum of 40 minutes per scenario of execution

  • strings cannot be more than 4M bytes (3.8MB) - use an external script, program to process data and then send a subset of the string into make via Webhook or standard output (eg SSH module). The UI bombs out at strings at 2MB or so. Try to eliminate processing large strings like this to avoid unintended consequences.

  • max file size depends on your plan

1 Like

the timeout limit is documented here:

:wink:

2 Likes

So where is your standard wall of text? I’m waiting

Bored Cabin Fever GIF

And also how can I forget these?

Tutorials are the best way to learn.

The Lord Of The Rings Wizard GIF

1 Like