Put the replace-before-use list above the code
Readers scan the code and copy it first. A list of values to replace above the block stops the copy-and-run mistake before it happens.
Technical & ProductContent Creator
Code snippet library: short examples with their assumptions stated
A code snippet library is a page of short code examples, each labeled with its language, its purpose and the versions it was checked against. Each entry should say what the snippet assumes and what the reader must replace before using it, such as a placeholder for an access key. The page holds a copy of the code, so it does not run, test or sync snippets with your repository.
Section outline
The entry layout every snippet follows
Library summary
One sentence on the languages and tasks the library covers, and who should use it.
50 wordsEntry header
The snippet name, the language, the version it was checked against and the date of that check.
40 wordsPurpose and assumptions
What the snippet does, what input it expects and which cases it does not handle.
100 wordsCode
The code itself, short enough to read on one screen, with placeholders written in capitals.
120 wordsReplace before use
Each value the reader must change, with one line on what it should contain.
60 wordsTest note and source
What was run and with which inputs, what was not covered, and where the code came from and whether it may be shared.
80 words
Total: 450 words
Example excerpt
Sample entry: formatting a receipt date
Sample section
Illustrative example: the team, its name and the snippet are fictional. Format a receipt date (Python 3.12) Checked against: Python 3.12, on 2026-10-02. Source: written by the Marlin Street team for its own receipts. Purpose: Turns a UTC timestamp into a short date for a printed receipt, in one time zone. It does not check that the zone name is valid, so an unknown name raises an error. Requirements: Python 3.9 or later, because the zoneinfo module arrived in that version. On Windows, install the tzdata package so that zone names can load. Replace before use: TIME_ZONE_NAME, for example America/Chicago. from datetime import datetime from zoneinfo import ZoneInfo def receipt_date(timestamp_utc: datetime, zone: str = "TIME_ZONE_NAME") -> str: local = timestamp_utc.astimezone(ZoneInfo(zone)) return local.strftime("%b %d, %Y") Test note: Run with three timestamps: one in January, one in July and one just before midnight UTC. Not tested on other Python versions or on Windows.
Format notes
Format entries so readers copy the right thing
Keep one language in each entry
Mixing languages in one entry forces readers to hunt for the part they need. Give each language its own entry, and put the language in the title and the header.
Show only the lines that matter to the task
A snippet with imports, logging and error handling for ten unrelated cases is a tutorial, not a snippet. Trim it to the task, and say what you removed.
Choose a dedicated tool when code must stay in sync
A static page is a copy, and it does not change when the source does. For one developer's personal snippets, an editor's snippet manager fits better. For code that must match a repository, generate documentation from the repository and run its tests there.
Mistakes to avoid
Mistakes that turn a snippet library into a liability
Real credentials in examples
A key pasted into an example is published with the page and cannot be taken back. Use a placeholder such as YOUR_ACCESS_KEY, and check the page for anything that looks like a secret before you share it.
Presenting a copy as the source
A snippet on a page does not change when the repository changes. Name the file or repository each entry came from, date the entry, and replace it when the source changes.
Labeling untested code as tested
A test note has to describe what you actually ran. Works tells the reader nothing; ran with three inputs on Python 3.12 tells them what to expect.
Copying code you may not share
A snippet from another project may carry a license that requires attribution or bars republishing. Check before you add it, and record the source and license in the entry header.
Hiding the limits
Readers assume a snippet handles the cases they have. List what it does not handle, such as empty input, very large files, other languages or older versions.
Frequently asked questions
Can a code snippet library page run or test my code?
No. The page shows text that a reader can copy. It does not run the code, check its output or compare it with your repository. The test note records what you ran, and you do that check before you publish.
Should code live on a page or in a repository?
Keep code that must stay correct in the repository, with its tests, and link to it from the page. A page can hold short examples that show a pattern, with a note that the repository is the source of truth.
Is a REST API example the same as a code snippet?
A REST API example is one kind of snippet: a short request and the response it should produce. In a library, label it with the endpoint, the method, the version it was checked against and placeholders for the access values.
How is a snippet library different from API documentation?
API documentation describes what an interface accepts and returns. A snippet library shows short examples of calling it, each with its assumptions and its replace-before-use list. Link the two: the documentation holds the rules, and the snippet shows one example of them.
Browse by category
More references in Technical & Product
References
API Documentation
References
Release Notes
References
Onboarding Guide
References
Knowledge Base
References
Tutorial Page
Visuals
Product Roadmap
How to build it
Follow the eight-step wizard: type, assets and description, images, branding, contact and call to action, Atty Suggestions, blueprint, and generate. Atty generates one HTML page in the background. Review it, then publish and share the page link or download the HTML file.
