One of my favorite things about Glitch is that the whole product is built with code sharing in mind. Every public project on Glitch has a “remix” button that allows users to make their own copy of an app, and continue building. It’s amazing to see all the projects that are remixed from a single app, and take such different directions.
I’m a member of the Solutions Engineering team and we’re dedicated to building apps that are easy to remix in order to help people build something great. As part of that, writing good documentation is critical. Here’s the checklist that our team uses to know that an app is ready for prime time. I hope it makes it easier to get started building reusable apps on Glitch (or anywhere on the internet!)
Write a descriptive README
A good README should start with a description of the project, an overview of the file structure, and links to any relevant documentation. This should be written in plain language so anyone can get a gist of what your app is doing, and how they can use it in their own project.
You can never assume someone’s familiarity or that something will be “obvious”. For that reason we include the real estate tour of the file structure. This can be as simple as saying: “styles.css is the file that controls the look of the app”, “/views is the place where the HTML files live”.
At the very end, I like to add a list of links to additional documentation that might be helpful. If your app is dependent on any packages or templating languages you should link them so folks can have an easy reference. We also link any other related Glitch projects or starter kits that might be helpful.
The README is also the place to tell users where they can make the project their own, and customize. This could be different endpoints on the API to try, different visualization on charting library.
Add setup instructions to the README
READMEs should have a section that covers all the setup instructions for when a person remixes. This can include any account setup they might need to do, as well as telling them to put their API keys into the .env file.
As .env files are secret, Glitch doesn’t copy over the credentials when someone remixes. Calling out in your README where folks need to add their keys ensures that the remixer won’t be discouraged when the app errors. They’ll be empowered to get it running using their own info!
Write meaningful comments in code
We err on the side of over communicating, and have comments for all the critical pieces of the codebase. Make sure your comments are written in plain language, and are descriptive.
Aim to describe what every function does. Your goal is that any user can jump in and very quickly get a sense of how the code works.
If there are easy ways to customize an app, I also like to add that in a comment. Include some text encouraging folks to “uncomment the code to see the change.”
Update the app description & project avatar
To update this, go to your project editor, then click the project name in the top left. There’ll be a field to write a description of what your app does. Make it descriptive, and list any big technologies or tools you’re using. Here you can also upload a new icon for your app.
Clean up your codebase
Make sure you remove any code you aren’t using. This can be leftovers from past iterations, a function you commented out, a variable you never call, or maybe a npm package you’re no longer using.
Also take a step back to consider if the structure is right for the type of app you’re building. Are you using the features of Express or would a simple webpage would do the trick?
Have someone else try remixing
Ask a friend who’s unfamiliar with your project to try remixing. Did the app work immediately? Were there any steps that were missing from your documentation?
Share your app with the world.
Be sure to @glitch on Twitter so we can see what amazing things you’re building. And follow us here on Dev.to to get the latest from Glitch.
Like this checklist? We made an app that you can remix and modify for your own workflow!
Top comments (2)
According to this help article, setup instructions should go in a
Setup.mdfile. Has that guidance changed?Good catch, we're updating the help docs so we'll definitely address that. Also interesting is you can have a
glitch_readme.mdfor glitch specific instructions in case the app has some differences when running on Glitch.