6 Guidelines for Documenting Your No-Code Software – Built In
I’ve released almost 200 versions of my web-based app to paying customers over the last 18 months. And I’m not even officially on version 1.0 yet. So last week, when I released version 0.9.24.25 via my no-code platform of choice, Bubble.io, I broke … well, almost everything.
What’s worse, it wasn’t a catastrophic break, the kind you can find with a few minutes testing. But a few days later, a customer reached out to support with a strange issue. It led me to discover a glitch in my logic I otherwise never would have caught. It could have lingered for days and made a huge mess of my data.
Thankfully, I was able to go back to my documentation, realize what I did and when I did it, and make a quick fix. It took me about five minutes to find and fix the glitch, and it only impacted that one customer. If it seems like I’ve been going on about documentation recently, that’s because I have been — for good reason. Without documentation in this case, it could have taken weeks before I realized what I had done, and maybe just as long to remedy it. All while revenue slipped through a gaping hole in my app.
No-code is no joke.
I’m a former (recovering) developer. And one of the reasons I love no-code so much is because of all the stuff I don’t have to do, like set up the infrastructure, rebuild a lot of functional wheels, and learn and remember the minutiae of syntax. But there’s one practice I made sure to carry over from my development days, because I remember how hard it was to fix shit when people were screaming at me.
As foreign a concept as “documenting no-code” might sound, it’s absolutely crucial, not only for recovering from your mistakes, but to keep you from getting lost in the weeds as you build a bigger and broader application or serve a wider market.
The good news is that you don’t have to be a developer to properly document no-code. The bad news is that there’s no form, format, or even a central repository to keep track of all the parts of your app, customized across disparate platforms.
But again, as a former developer, lifelong product entrepreneur, and now veteran no-coder with a working and profitable business built solely on no-code and low-code platforms, I think I’ve got a good solution.
You do what works for you, but make sure you follow these six tenets.
The main reason why no-coders don’t document is because there’s no place to do it. It’s a silly reason until you think about it. When you’re not writing code, there’s no place to comment. There’s also no GitHub, no single, central place where your work is taking place.
For example, right now I’m mostly using Bubble.io as a backbone to connect MailChimp, which I’m over-customizing the crap out of, plus some Stripe tweaking, connecting it all with Zapier like duct tape, and slapping on four or five more helper apps.
But here’s a developer secret. Good developers will keep a scratch pad open while they code — like a text editor or a Google doc — just to keep track of their logic while they try to do a dozen different things at once. No-coding is really not that different. I like to use a Google doc and I have it open all the time.
Read More About Software Engineering and Development on Built In’s Expert Contributors NetworkThe Back-End Tech That Front-End Developers Need to Know
I never touch a setting or connect a webhook or even change a font type without writing down what I’m going to do before I do it.
Documenting your code after the fact usually results in two mistakes. One, you don’t do it, because if you’re good at building, you take all your available time (and then some) to build. Two, you don’t remember at least half of what you just did, certainly not in detail.
Documenting before the fact requires patience and commitment, but it pays off, especially when you’re done “coding” and just have to check off everything you’ve just done instead of writing it all out from scratch.
Explain everything you’re about to do in detail. As you’re working, come back to the document with the actual names of platforms, objects, functions, data and variable names, everything you just created and what it touched.
Pretend you’re writing the document for someone else who is not you, someone who is walking in cold with no knowledge of what you’ve been doing. Because if you’re successful, chances are this will happen. When I sold one of my companies years ago, they brought in their own CTO for a standard technology transfer, and I sat with that person for a month demystifying my (pretty well documented) maze of code.
But also be direct. Don’t write pages of documentation, write short bullet points. Bold format major areas or different platforms so you can scroll through your doc and, at a glance, figure out where your problem might be.
Oh, also, make sure you jot down the date of when you made the change and the date the new version went live. Use proper version numbering every time you release. And stay away from shorthand, acronyms, or any of your own language.
Example:
Read More About Software Engineering and Development on BuiltIn.com13 Code Review Tools to Know
Here’s another developer secret. One of the primary reasons why software breaks is because the developer got something to work but didn’t understand why it worked. It just worked, so they shipped the code. Then it broke, and now they can’t figure out why it’s broken because it worked before.
“Before” meaning the time before a hundred other changes to the code base happened after that leaky code got deployed.
No-coders will fall into this trap over and over again, because the platforms are so smart that they will make just about anything you can do “work.” Until it doesn’t. So make the extra effort to understand why you’re doing what you’re doing, then write it down. That way when it breaks weeks or months down the road you won’t lose your mind trying to figure out why you did it the way you did it.
Example:
Don’t push too much to production at once. You have to balance between tipping a lot of small apple carts versus tipping one giant apple cart. But believe me, the smaller apple carts are much easier to clean up.
Usually, unless it’s a quick “hot” fix, your only remedy for a mistake in production is to roll back to the previous version. A lot of platforms are very good at this, but if you’ve spent weeks or months working on a release and delivering it all at once, you’ll be looking for a needle in a haystack while you send your customers back to a version that may be jarringly old.
Example:
That’s it. That’s the whole version. It does more than you think, but not much more.
Read More About Software Engineering and Development on BuiltIn.comWhen ‘It Works on My Machine’ Just Doesn’t Cut It
Some platforms allow you to create save points and restore to previous versions like I mentioned above, but most don’t do it well, and some don’t do it at all. Make your own backup copies of text, scripts you’ve modified, settings you’ve changed, anything that would require a lot of rethinking to to re-do.
Writing great code isn’t about knowing secret words and languages that no one else does. It’s about making apps do great things elegantly. That takes a lot of imagination, perseverance, and time. Don’t let your best critical thinking fade into the void as you tackle the million other things that come with running a business.
Built In’s expert contributor network publishes thoughtful, solutions-oriented stories written by innovative tech professionals. It is the tech industry’s definitive destination for sharing compelling, first-person accounts of problem-solving on the road to innovation.
