As some of you may already know, I have been fortunate enough to have a chance to work with Bubble with the goal of improving the written documentation on manual.bubble.io.
For the last few weeks we’ve been hard at work planning the coming updates and I’m excited to share the first batch of significant updates.
Let’s first dig into what we’re trying to do here.
Goal
First, it’s important to emphasize that the project focuses on the written parts of the Bubble manual for new. The goal with this project is to ensure that Bubble’s written documentation is:
- pleasant to read, easy to understand and helpful for Bubble developers on both a beginner and advanced level
- covering every aspect of their topic
- generally of high quality
Project progress
The manual is a large body of work and updates will happen in steps. We have been collecting feedback from users of all levels to get an understanding of how the current manual is perceived and collecting suggestions for how it can be improved.
We have been using data on page visits to rank the importance of specific articles, combined with user feedback and our own general “common sense” for how updates can best serve the community. As a result, we decided to first rework the documentation covering the Bubble API and the API Connector.
Why these topics?
These topics were selected for the first batch of updates for a few reasons:
- The existing articles had a high page visit count
- The topic of APIs is among the more complex and challenging things to learn for new Bubble users
- It would allow us to write about a technically intricate subject to learn more about how we can reach users of all experience levels – in other words: are we able to explain it in a way that makes both beginners and experienced users find it useful?
- Lastly, it allowed us to test how it would be received if we spend significant chunks of the manual explaining technical details that are outside of the Bubble realm, such as how RESTful APIs work in general.
Article links
There are three series covering APIs, totalling 25 brand new articles:
Introduction to APIs
The Bubble API
The API Connector
Additionally, we have added an API glossary, as well as revamping the core reference page for Data API requests.
I’m excited to hear your feedback on the changes to these articles and whether you agree with the direction in which we’re moving.
Technical updates
We’ve also made use of some new tools to try to make the documentation easy to follow:
Annotations
You will find annotations on technical terms in the new articles that you can click to get more information about a specific word, and sometimes links to extended explanations. We hope this will make it easier for beginners to understand the terminology without drowning the articles in too much repetitive explanations.
Expandable sections
If we find that a central part of the terminology of an article may need further explanation for some users, but we also think that a lengthy explanation would weigh down the article too much, we hide the extra information by default in an expandable section. We sometimes also use this to link to other sections that users may find relevant. In the example below, we give further insight into the HTTP protocol (which can be helpful to know if you are working with APIs), but many users would find it out of place in the article itself:
Interlinking
We have also tried to insert relevant links more broadly where we think it can be useful, as well as linking between the User manual and Core reference sections:
API requests documentation
To make the available Data API requests in our core reference more complete and easy to navigate, we have placed the calls in expandable sections that highlight the purpose, technical details and possible errors. Each call also includes a list of possible solutions to different errors.
Update log
One requested feature was for us to communicate more clearly when the manual has been updated. For example, agency owners may want to share that information with their developers to stay updated on important topics. You will find the changelog here.
Providing feedback
Each of the new articles now contain a link that lets you provide feedback for that specific article. You’ll find it in an expandable box at the top of each article:
Thank you for reading this lengthy thread, and I’m very excited to hear your thought on the updates and the direction we are taking. Over time, we want the Bubble Manual to become the best in the industry, and the way to get there is through the community.
- and can’t think of anyone better to do this tricky work. Very tricky work!
- and can’t think of anyone better to do this tricky work. Very tricky work!