Newsletter: How to write docs so good developers will cry

[ivanagas]

Changes

Feedback appreciated:

• Any points I'm missing?
• Any good examples I should include?
• Did I go overboard with the images?

I know it is a bit long and overwritten, but I decided I would go with this to start and edit it down.

Checklist

• Words are spelled using American English
• Titles are in sentence case
• Feature names are in sentence case too
• Use relative URLs for internal links

Article checklist

• I've added (at least) 3-5 internal links to this new article
• I've added keywords for this page to the rank tracker in Ahrefs
• I've checked the preview build of the article
• The date on the article is today's date
• I've added this to the relevant "Tutorials and guides" docs page (if applicable)

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
posthog	✅ Ready (Inspect)	Visit Preview	Feb 4, 2025 6:59pm

[andyvan-ph]

I don't love this, tbh. Reasons why:

• It all feels a little high-level and and obvious. Nothing in it surprised me or made me want to share it.

• It doesn't feel that opinionated. Obviously there are opinions in there, but it doesn't feel like we have something important to share here. Case in point, our final point is "Don't reinvent the wheel".

• Just structurally, it feels a little formulaic / SEO-like.

I still think "docs" as a topic is potentially interesting, but maybe we can find a different way to tackle it?

[andyvan-ph]

Did some thinking about what might work and I feel like it needs a format that grounds it real world examples.

Something like "The X characteristics of great documentation" (bad headline) where it goes:

• Good docs do X
• Explain X
• A good example is Stripe / [whatever company]
• Screenshot of what you're talking about
• Break down why it works / why it's good

And then repeat.