- developer marketing newslepear
- Posts
- 🍐#133 How to create a good GitHub Readme, and tips for “writing” incredible developer content
🍐#133 How to create a good GitHub Readme, and tips for “writing” incredible developer content
High on pear juice
Jakub Czakon
November 02, 2025
Hey,
We went to farm hotel thing with the fam. And my daughter made me a carrot + pear🍐 juice. Yes, she is the best. And ok, her rabbit helped a bit too. Exhibit A:
This week on the agenda:
How to create a good GitHub Readme
Tips for “writing” incredible developer content
+ a few bonus links at the end
Total pearusing time: 7min
Before we start a word from this week’s sponsor:
Looking for your next creator collab?
Our Creator Showcase is live, with YouTubers, influencers and newsletter writers to give you inspo for your next campaign.
Explore and find the voices your dev audience already trusts.
👉 [Meet creators that code - on Plug.Dev]
Developer marketing insights
1. How to create a good GitHub Readme
Recently a few clients asked me to tear down their GitHub Readme's which was the final straw to prepare a doc I could share with good examples and principles.
As always this is a work in progress but should already be helpful. Any feedback, suggestions, insights, examples are very much welcome.
TLDR my default structure suggestion is:
Banner (Logo + Tagline + Visual)
Badges
Links (Website, Docs, Examples, Blog, Discord)
About (What it is)
Visual Demo (GIF, Video, Screenshot, Code Snippet etc)
Installation
Getting Started / Quickstart / Basic usage examples
Features list
How to Contribute
License
You can optionally add, Features, Architecture, Links & Resources, Limitations and FAQ. If it gets very long add a Table of Contents. But Readme is a single doc, navigating through it will never be fun when it is very long so keep it short and send to docs or examples where it makes sense.
Make it visual with GIF, tables, code snippets, bullets. Keep it as short as possible but NOT shorter. It has to be clear and guide people to a first accomplishment. For everything else, send people to the docs.
More context, examples, and resources in the article.
2. Tips for “writing” incredible developer content
Couple weeks back I shared a bouncing balls LinkedIn post inspiration, and to my delight, Jack Bridgert got the author of that post on the Scaling DevTools Podcast to talk about content. Amazing.
Comments/takeaways:
Create something actually valuable: The goal of every touchpoint is “leave people smarter even if they never buy.” Real education that upgrades the your mental model (in this case databases, latency, replication). That compounds into brand trust over time. Funny enough Digital Ocean had that concept of “developer love” in their content strategy (wrote about it here).
High-effort, interactive content beats AI slop: Ship fewer, better pieces. Interactive explainers (d3, live simulations, benchmarks in their case) take weeks or more to create. But they stand out, people share them. They smell like value. They make devs engaging with it on Twitter look smart by association (which is a concept from a book Contagious btw.
Educate into the launch (soft CTA): If there is a product story wrap it in a learning that stands on its own and then connects to a product. Ben’s latency deep-dive taught the problem, then casually pointed to PlanetScale Metal as the fix. Love this comment that someone wrote that sums up what you are aiming for → “So good I forgot it was marketing.” Also, this reminded me of a story/framework that Tailscale seemed to use for Hacker News: Problem → Obvious solution → Why it doesn’t work → Product → How it works exactly → Try yourself (wrote about it here).
Do the hard work: research, benchmark, get feedback: Pick topics from real pain (performance, reliability), show numbers wherever you can (they frame the story + show you’ve actually done smth not hand waved it), and invite brutal edits from dev peers. Leave, return, refine. Ask, “Would a {your buyer: DB/DevOps/frontend} engineer read this?” If not, rewrite. Then come back to it and rewrite again. This takes time but makes for great content.
This reminded me of a short piece I wrote some time ago “How to test if what you created will resonate with developers?”.
The basic idea in there was to:
take a fresh look at what you created (extra tip is to edit/review on a different day than you write/create)
imagine yourself stand in front of a dev you respect and present this
do you feel proud, or ashamed?
do you think this was written to add value to them?
or “it was just a marketing content” which unfortunately almost always means that smth was written for a disrespected but unclear audience that will consume it in an unknown location
Respect your audience, try to actually help/add value. You will be fine.
Need more developer marketing insights?
1. Work with me 🍐
"You helped us land messaging that clearly states the problem and solution in the words our champions actually use. The homepage is super crisp now."
If you want my help I do Workshops (60-minute session on whatever you want), Teardowns (audit+suggestions for your homepage, messaging, ads etc), and longer-term Advising.
2. Bonus links to check out
3. Join our Slack community
"Been here 20 min and already folks are sharing great advice."
2400+ dev tool CMOs, heads of growth, product marketers, and other practitioners talking shop.
Reply