Someone asks for help and you paste forty lines into Slack. It wraps at column sixty, loses its indentation, and scrolls off the channel in an hour. Or you paste a screenshot of code, which nobody can copy, search, or read on a phone. Sharing code well takes about the same effort as sharing it badly, and the difference decides whether anyone can help you.

Match the Medium to the Size

The mistake at each boundary is the same: using the smaller medium one step too far. A 200-line paste in Slack is unreadable and unsearchable, and it pushes everyone else’s conversation off screen.

Never share code as an image. It can’t be copied, searched, read by a screen reader, or viewed sensibly on a phone. The only legitimate case is when the rendering is the point — a terminal colour bug, an editor UI issue.

Fenced Blocks, With the Language

Example:

```ruby
def total_cents
  line_items.sum(&:subtotal_cents) - discount_cents
end
```

The language tag costs four characters and buys syntax highlighting everywhere — Slack, GitHub, most chat clients. Without it you get grey monospace and the reader loses the visual structure that makes code scannable.

Slack specifically: triple backticks on their own lines, not inline. And turn off the WYSIWYG formatting toolbar in preferences — it mangles pasted code more often than it helps.

The Gist Checklist

A gist is a git repository, which means it can hold multiple files, and most people never use that.

# Create from a file, public, with a description
gh gist create order_totalizer.rb \
  --public \
  --desc "Reproduces the rounding bug in Order#total (Rails 7.1, Ruby 3.2)"

# Multiple files at once
gh gist create totalizer.rb totalizer_spec.rb Gemfile --desc "..."

# From stdin
bundle exec rspec 2>&1 | gh gist create - --filename failure.txt

# Secret gist — unlisted, but anyone with the link can read it
gh gist create notes.rb

gh gist list
gh gist edit <id>

Four things that make a gist actually useful:

1. A real filename with an extension

gistfile1.txt gets no highlighting. order_totalizer.rb does. The extension is the only thing GitHub uses to pick a lexer.

2. A description that says what it is

The description is the title in every listing. “Ruby” tells nobody anything. “Reproduces the rounding bug in Order#total (Rails 7.1, Ruby 3.2)” tells them whether to click.

3. Files in reading order

Gist orders files alphabetically. Prefix them if the order matters:

1_problem.rb
2_current_output.txt
3_expected_output.txt
4_gemfile.rb

4. A README

Add README.md and GitHub renders it at the top of the gist. That’s where the context goes — what this is, how to run it, what you observed.

Make It Reproducible

The difference between a snippet someone glances at and one they can help with.

Example:

# repro.rb — run with: ruby repro.rb
require "bundler/inline"

gemfile do
  source "https://rubygems.org"
  gem "activerecord", "7.1.3"
  gem "sqlite3"
end

require "active_record"

ActiveRecord::Base.establish_connection(adapter: "sqlite3", database: ":memory:")

ActiveRecord::Schema.define do
  create_table :orders do |t|
    t.integer :discount_cents, default: 0
  end
  create_table :line_items do |t|
    t.integer :order_id
    t.integer :subtotal_cents
  end
end

class Order < ActiveRecord::Base
  has_many :line_items
  def total_cents = line_items.sum(&:subtotal_cents) - discount_cents
end

class LineItem < ActiveRecord::Base
  belongs_to :order
end

order = Order.create!(discount_cents: 50)
order.line_items.create!(subtotal_cents: 33)
order.line_items.create!(subtotal_cents: 33)

puts "Expected: 16"
puts "Actual:   #{order.total_cents}"

bundler/inline is the underused tool here — a single self-contained file that installs its own dependencies and runs with ruby repro.rb. No repo to clone, no bundle install, no setup instructions to get wrong.

A maintainer who receives this can reproduce your bug in twenty seconds. One who receives “my totals are wrong, here’s my model” cannot, and will ask three clarifying questions across three days.

Include the Context, Not Just the Code

Every shared snippet asking for help should carry:

**What I expected:** `order.total_cents` → 16
**What happened:**   `order.total_cents` → 66
**Versions:** Ruby 3.2.2, Rails 7.1.3, PostgreSQL 15
**What I've tried:** Checked that `discount_cents` is populated (it is, 50).
Isolating `line_items.sum` returns 66 as expected, so the subtraction
appears to be the issue.

Four lines. They eliminate the entire first round of questions, which on an async team is a day.

And paste the actual error, all of it, as text:

```
NoMethodError: undefined method `subtotal_cents' for nil:NilClass

  app/models/order.rb:12:in `block in total_cents'
  app/models/order.rb:12:in `sum'
  app/models/order.rb:12:in `total_cents'
```

Truncating the trace to the first line removes the part that identifies where it came from.

Pro-Tip: Redact before you paste, and assume anything shared is permanent. Real customer emails, account ids, API keys, internal hostnames, and database contents routinely end up in public gists and in Slack channels that get exported. Build the habit of substituting as you write — [email protected], account_id: 42, sk_test_REDACTED — rather than reviewing afterwards, because afterwards you’re focused on the bug and won’t see them. A secret gist is unlisted, not private: anyone with the URL can read it, it’s indexed if the link is ever posted publicly, and deleting it doesn’t remove it from caches. If the snippet genuinely contains production data, share it in a private repo or paste it in a channel with retention limits, and rotate anything credential-shaped regardless of how quickly you deleted it.

Snippets Worth Keeping

Gists also work as a personal reference — the psql incantation you look up every six months, a working example of an API you use rarely.

# Find your own
gh gist list --limit 50
gh gist view <id>

# Clone one and edit it as a repo
gh gist clone <id>

Two habits that make the collection usable a year later: describe every gist properly at creation time, and add a comment at the top saying when it was written and against what version. A snippet with no date is a snippet you can’t trust.

For anything the team uses more than twice, promote it out of a gist and into the repo — a rake task, a script in bin/, or a section in the README. A gist that becomes load-bearing is a single point of failure attached to one person’s account.

Conclusion

Match the medium to the size, always tag the language, and never share code as an image. For anything substantial, use a gist with real filenames, a description that says what it is, and a README.md for context. Make bug reports reproducible with bundler/inline so a single ruby repro.rb demonstrates the problem — that one technique does more to get you help than any amount of explanation. Include expected versus actual, versions, and the complete error text. Redact as you type rather than afterwards, and move anything the team depends on out of a gist and into the repository.

FAQs

Q1: Are secret gists actually private?
No — unlisted. Anyone with the URL can view it without authentication, and it stays reachable after you think you’ve hidden it. Use a private repo for anything genuinely sensitive.

Q2: Can gists be version controlled?
Yes, every gist is a git repo. gh gist clone <id> gives you a working copy, and pushes update the gist with full revision history visible in the UI.

Q3: What’s the best way to share a long log file?
A gist as a .txt or .log file, or gh gist create - from a pipe. GitHub truncates very large files in the browser, so trim to the relevant window first — nobody reads 40,000 lines anyway.

Q4: How do I share code with someone not on GitHub?
A gist URL works without an account for reading. For a self-contained runnable example, the bundler/inline script pasted directly is often better than any hosting.

Q5: Should team snippets live in gists?
Only as scratch. Anything reused belongs in the repo — a bin/ script, a rake task, or documentation — where it’s versioned with the code it relates to and doesn’t disappear when someone leaves.