It has now become apparent that, while the vast majority of no-coders are indeed trained in the use of the tool, they are not necessarily trained in the appropriate methods, nor in the specific computer culture: algorithmic logic, databases and data processing, API, versioning, and the associated documentation. There are a certain number of good practices within the developer world, that must be transposed to the no-code world. However, “we cannot lie”... documentation is not the most exciting part of a project, and its editing is often put off to the last possible minute...
Documentation is, however, a key factor in success and sustainability: we identified its importance while interviewing start-ups .
When should I document my no-code environment?
Nowadays, the main, and most common reasons behind the selection of a no-code solution are:
- For an entrepreneur: the development of an MVP
- For an existing company: the acceleration of the technical roadmap, the development of an internal tool, the development of a new service offering, the automation of its processes, the replacement of an existing tool, the replacement of an interface...
In either case, if the no-code solution is used to prototype an application and test its feasibility and efficiency, the main concern will be that this can be done quickly. With a bootstrap operating method; with a small number of players interacting with one another, documentation is naturally not a priority.
The Bus Factor represents the number of people who would have to be “hit by a bus” before your organisation would be in danger. This is a factor that demonstrates the significance of the risk associated with the non-sharing of information and competences within a team.
In spite of the importance of sharing information so as to be able to deal with the infamous Bus Factor, the need to document one’s no-code environment arises whenever several people are brought together in collaboration.
We can see that without MVD (Minimum Viable Documentation), working in teams of several people can prove chaotic: incompatible changes, accidental deployment to production... The lack of documentation can become extremely counter-productive. If you encounter this type of situation, it’s high time that you address this issue.
Documentation must be considered a standard practice and not a box-ticking exercise. It must be thought of as a genuine productivity tool.
How do I document my no-code environment?
The tools that are currently and most commonly preferred when it comes to hosting and collaborating on documentation are notion.so or coda.io. These tools allow you to store or integrate (embed) information that is highly diverse in terms of its nature or source (diagrams, tables, wireframes...). Comment: Generally speaking, it still remains more practical to work directly within source tools (e.g. Miro, Figma...), the objective of inserting them into the documentation is the sharing and centralization of information.
Components to consider
Some of these components may appear trivial, however, having this information available in a centralised manner represents a genuine timesaving for the entire team – therefore, they must not be neglected. It is not necessary to have ALL of the elements listed below, the key terms here being good sense and pragmatism: you must document what is useful and adds value. This will depend a great deal on your context and will without doubt evolve over time, as your platform becomes more complex, your team increases in size, and your number of interfaces multiplies...
- Key contacts:
- Team contact details (including emergency number!)
- Contact details or status of any service providers, for example:
- List of the tools used and corresponding login details: so that you can quickly add members to, or remove members from the team
- Adopt a shared language: explain the naming conventions, standardisation rules (to be adapted depending on the tools used)
- Modelling of your platform
- User flow,
- Modelling of business processes (BPM - Business Process Model)
- Conceptual data models (ERD - Entity-Relationship Diagram)
- Tools such as Miro or LucidChart are very accessible and easy to use. However, at the moment, only Miro has integration for notion and coda. Below you will find a number of useful resources to give you a better grasp of these topics.
Adopting shared rules and naming conventions will be essential to ensuring that you are all speaking the same language. For example, at Gojob, a prefix in the name of the scenarios enables the designation of the person in authority, who must ensure that the system is functioning properly.
- Design: Figma also offers integration; allowing you to integrate your Wireframes into your documentation.
- External components and interfaces: list of plugins (those used, but also those that have been tested and that people have stopped using, and why!), list of APIs used with useful information (link to the API’s developer doc, if applicable: token validity date...)
This list is not exhaustive. It will have to be adapted to your own situation.
The next challenge will be to successfully and regularly update this documentation, not out of a desire to tick boxes, but because it is genuinely useful: documentation must serve as a tool. This requires rigour and discipline.
Nonetheless, the feedback that we have received indicates that, for growing structures, you ultimately waste less time if you document on a regular basis rather than constantly having to search for information when this documentation is not in place.
The creation of a documentation system is a prerequisite to working effectively as a team. A necessary, albeit insufficient requirement, no-code stacks can be highly fragmented, the tools used are not always adapted to group work, and therefore it is essential that you are sufficiently well organised.
Neodelta (documentation of a Make scenario)
Context: a collective of digital process optimisation freelancers, working, in particular, with no-code tools used for documentation: Notion
- Scenario titles = what it does + version no. + date of last update)
- Using the same emojis:
- 🔍 for a search function
- ⬆️ for outgoing actions
- ⬇️ for incoming actions
- Short titles for the steps so that they can be easily found
Example of a scenario using these good practices:
Example of one of their documentation pages in Notion:
- Name of the scenario
- History of modifications with the name of the version and the date
- Function: action-by-action explanations as to how the scenario works, with the logics for each action
Unly (documentation of the no-code stack)
Context: Edtech uses as much code to develop its various products as it uses no-code – use of the following tools: Stacker, Airtable, Zapier, Make, Notion. Tools used for documentation: GitHub with document versioning in markdown format.
The Git repository:
Tree: Tool name > Functionality > readme.md
Content of the readme.md file:
The objective is to have all of the elements that are present in the no-code scenario parameters – this is a lengthy manual task, however, is essential for the proper maintenance of the environment. 20-30% of development time is dedicated to documentation.
Example for a scenario:
- Link to the scenario editor
- Link to an explanatory video (ScreenCastify)
- Link to the element logs, if they exist (in this case, the Zapier logs)
- All the parameters of the trigger
- All the parameters of the actions
In addition to scenarios, other elements are also stored in this knowledge base, such as formulae or scripts, so that they can be referenced in the same place.
Formula for an Airtable column
💡 The benefit of having everything in text format is the ability to perform a full-text search, which allows you to see the field name dependencies between Airtable and Make, between an Airtable script and an Airtable column, with a view to modifying throughout prior to release.
Here you can see the presence of a firstname field in an Airtable script – you must therefore update the script if the column name is modified.