How to structure and share code examples

If the example you need to share is in just one file (or a few files, for an advanced audience), consider sticking to the code-as-exhibit approach and embed it in the article with clear directions for where to copy and paste it to. Doing it this way makes it super simple for both publishers and users, and is very easy to understand and maintain. Since the code quickly ends up in the user’s hands, it’s also a good choice for code samples that require editing to work, such as “add your API key on line 3” rather than trying to walk through setting an environment variable so that a cloned code sample can run unchanged.

If a user might only need one example, or there are a lot of files that are themselves a project, then one-repo-per-example is a good model. For example, creating template repositories for quickstarts that can be used to scaffold applications.

The downside of having lots of example repos is that now you have lots of example repos to monitor, maintain, and look after! I’ve had good success using some of the GitHub features (adjust to fit your preferred source control platform) to help manage things:

Leave a Comment