Writing for technical audiences often means sharing code in one form or another. If the code is only for illustration purposes, then it can be included in the article for observation. But if the code is useful or reusable by your readers, then you need a way to make it available to them. I’ve seen a few questions on this recently (shout out to the DevRel Collective slack for a brilliant discussion AND nagging me to write it up as a post!), so I’m sharing my experiences on how to publish and maintain code in sane ways!

To help you think more about what you’re trying to do, there are some criteria that might help.

Single file or simple code

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.

Pro-tip: Make sure the destination publishing platform has an easy “copy” button on code samples.

Use one example from a selection

If you create content for developers, you quickly amass a LOT of shareable code. How much of that code does each user need?

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:

• Add a codeowners file to every repository so that pull requests always have an owner and show up on someone’s review requests list! Make this a team name, so you can add more people into the team or easily update who should get these notifications if you have churn.
• Automatically set new issues on these repositories to be added to a GitHub project so you can track the maintenance of the projects all in one place. Enable dependabot or an equivalent as well, and then you can tackle updates in batches as needed. You can automatically add the pull requests to a board as well.

Lots of examples, using lots of files

When each code example spans multiple files, and users might want to use a few of them, or dip into them over time – that’s a good prompt to build up a library of examples in one repository. Use a clear structure, such as one folder per product with subfolders for each example, so that it’s easy to see what goes where, and to add new things in sensible places.

How far you go with making the examples instantly executable in this context, vs just making them available, is really up to you. Two rather divergent examples I’ve worked on are the Vonage code snippets and the Redocly CLI cookbook. The Vonage code snippets are executable, have automated testing for different versions of the technology they are for, and are included into the main developer documentation. This works really well for snippets that should be ready to use and to just drop into projects that already use the Vonage SDKs to perform simple tasks. The Redocly CLI cookbook is almost the opposite: the main README lists a lot of different examples, and each subfolder has a detailed README for the example and all the files needed to make it work. Users need to copy, paste and almost always edit parts of the provided example, and slot them in to their own project structure. Since each project is different, providing reusable source made sense there.

Code example upgrades

Whichever approach you choose, there are a few things that make every example better:

• Use meaningful values: swap foo and bar for product and basket, or illustrate attributes with colour, weight and horsepower. Good examples really are worth a thousand words!
• Words always help: Code examples are not self-explanatory. Introduce every example with what it does, and why you’d like to do that. Follow every example with what just happened and how to observe that is, in fact, what happened.
• Continue to care: if you publish to GitHub, subscribe to the issues and pull requests of where you’ve published it. If you publish to a developer portal, make sure you have access to the feedback for those pages. Let users tell you if something gets outdated or needs changing.
• There is no such thing as too many examples: Make as many examples as you can with the people/skills/time/energy you have available! People who write code will find the bits they need an mix-and-match to solve their own problems if you give them enough raw material to work with.