From 8ee2b33ce86585bf08eb8a05c70300e69d182577 Mon Sep 17 00:00:00 2001 From: Ian Vanagas <34755028+ivanagas@users.noreply.github.com> Date: Fri, 5 Jun 2026 15:44:34 -0400 Subject: [PATCH 1/3] writing blogs for engineers --- .../handbook/engineering/writing-blogs.md | 69 +++++++++++++++++++ contents/handbook/engineering/writing-docs.md | 2 +- src/navs/index.js | 6 +- 3 files changed, 75 insertions(+), 2 deletions(-) create mode 100644 contents/handbook/engineering/writing-blogs.md diff --git a/contents/handbook/engineering/writing-blogs.md b/contents/handbook/engineering/writing-blogs.md new file mode 100644 index 000000000000..aa8ea9a23825 --- /dev/null +++ b/contents/handbook/engineering/writing-blogs.md @@ -0,0 +1,69 @@ +--- +title: Writing blogs as an engineer +sidebar: Handbook +showTitle: true +--- + +We write and publish a lot of content at PostHog. focuses on this, but we also publish writing on our blog from anyone, including engineers. These usually look like: + +1. Guides like [A beginner's guide to testing AI agents](/blog/testing-ai-agents) + +2. Technical blogs about experiences and lessons learned like [Karpathy's Autoresearch found a 3-year-old bug in our query engine (and improved performance by 11%)](/blog/karpathy-autoresearch-query-engine-bug) and [Untangling Tokio and Rayon in production: From 2s latency spikes to 94ms flat](/blog/untangling-rayon-and-tokio) + +3. Opinionated blogs like [Being AI-native matters more than experience](/blog/ai-native-hiring) and [AI is killing no-code experiments](/blog/ai-is-killing-no-code-experiments) + +Why do we encourage writing blog posts? + +- You're doing cool things, others should know about it. PostHog [values making it public](/handbook/values#make-it-public). +- It helps us attract users, customers, and talented teammates. +- It's a reference point you can point at for future engineers, customers, and teammates. + +## What to write about + +PostHog's audience ([ICP](/handbook/who-we-build-for)) is the same as you: the people building products at high-growth startups. This means the posts you're interested in are likely the same as what they're interested in. + +There's a couple of frames that can help you decide if something is interesting enough to write about: + +1. Is it interesting enough to write up and sending to an engineering friend? +2. Would it be useful for you two years ago? + +If yes, then it's probably interesting enough to blog about. There's a huge amount that is obvious to you but not obvious to others. You're more of an expert than you think you are, especially when it comes to your personal experiences. + +## How to write + +Start by thinking about a reader's perspective: What will be interesting or useful to them? What do you want readers to come away remembering? + +Don't worry about some "PostHog designated style," there is no such thing. Write like you would in an email, Slack message, or RFC. Read through [our style guide](/handbook/content/posthog-style-guide) though, especially the first **General principles** section, but don't obsess over perfectly following it. The can help you and there's always exceptions. + +AI is helpful for research, outlining, line-editing, and finding weak spots, but please don't get it to write the entire piece for you. Readers can tell when something is written by AI and discount it. + +If you need a skeleton of post, many technical blogs look like this: + +1. Hook: The surprising result or pain you experience. +2. Context: What the state of things were. Enough so readers can follow. +3. Journey: The investigation of what you tried, what failed, and what succeeded. Include the "takeaways" as part of the journey. +4. Resolution: What actually changed? Give specifics, numbers, and/or visuals if you can. + +Use descriptive titles along the way rather generic ones like "Background" or "What we learned." If someone was skimming the piece, would the title give them the details they were looking for? + +## The details about publishing + +The general workflow for a post looks like this: + +1. Have an idea + +2. Share in the [`#content-and-video-ideas`](https://posthog.slack.com/archives/C015CRUQR7Y) Slack channel or write up outline or draft + +3. Open pull request of your draft in [posthog.com](https://github.com/PostHog/posthog.com). Blogs go in the [`/contents/blog` folder](https://github.com/PostHog/posthog.com/tree/master/contents/blog) (you can see the format from other blogs there). + +4. Get review from someone from the and (optionally) a relevant teammate. + +5. Iterate on feedback (usual 1-2 rounds) + +6. Fix formatting and styling details ( can help with this) + +7. Merge and it's automatically published on [posthog.com](/blog) + +Once published, you can share it on social ([LinkedIn](/handbook/content/linkedin), X, Bluesky, etc.), with relevant coworkers, and in relevant communities (like HackerNews, but be careful not to spam or ask for upvotes). This might feel a little cringe, but it's critical for actually getting people to read your writing. + +Remember, you're the driver on all of this. You don't need someone's approval to write a blog. \ No newline at end of file diff --git a/contents/handbook/engineering/writing-docs.md b/contents/handbook/engineering/writing-docs.md index 3a4399c270ea..6004ac82b5d8 100644 --- a/contents/handbook/engineering/writing-docs.md +++ b/contents/handbook/engineering/writing-docs.md @@ -1,5 +1,5 @@ --- -title: Writing docs (as an engineer) +title: Writing docs as an engineer sidebar: Handbook showTitle: true --- diff --git a/src/navs/index.js b/src/navs/index.js index fd4d03661745..ec1e1c472f6c 100644 --- a/src/navs/index.js +++ b/src/navs/index.js @@ -739,9 +739,13 @@ export const handbookSidebar = [ url: '/handbook/engineering/customer-comms', }, { - name: 'Writing docs (as an engineer)', + name: 'Writing docs as an engineer', url: '/handbook/engineering/writing-docs', }, + { + name: 'Writing blogs as an engineer', + url: '/handbook/engineering/writing-blogs', + }, { name: 'Working with Data Warehouse', url: '/handbook/engineering/data-warehouse', From 4113233b83e2f64efdc61792664c5840d78cea7c Mon Sep 17 00:00:00 2001 From: Ian Vanagas <34755028+ivanagas@users.noreply.github.com> Date: Fri, 5 Jun 2026 15:46:34 -0400 Subject: [PATCH 2/3] a couple more tweaks --- contents/handbook/engineering/writing-blogs.md | 10 +++++----- contents/handbook/engineering/writing-docs.md | 1 + 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/contents/handbook/engineering/writing-blogs.md b/contents/handbook/engineering/writing-blogs.md index aa8ea9a23825..b9cb32dea8a7 100644 --- a/contents/handbook/engineering/writing-blogs.md +++ b/contents/handbook/engineering/writing-blogs.md @@ -50,19 +50,19 @@ Use descriptive titles along the way rather generic ones like "Background" or "W The general workflow for a post looks like this: -1. Have an idea +1. Have an idea. -2. Share in the [`#content-and-video-ideas`](https://posthog.slack.com/archives/C015CRUQR7Y) Slack channel or write up outline or draft +2. Share in the [`#content-and-video-ideas`](https://posthog.slack.com/archives/C015CRUQR7Y) Slack channel or write up outline or draft. 3. Open pull request of your draft in [posthog.com](https://github.com/PostHog/posthog.com). Blogs go in the [`/contents/blog` folder](https://github.com/PostHog/posthog.com/tree/master/contents/blog) (you can see the format from other blogs there). 4. Get review from someone from the and (optionally) a relevant teammate. -5. Iterate on feedback (usual 1-2 rounds) +5. Iterate on feedback (usual 1-2 rounds). -6. Fix formatting and styling details ( can help with this) +6. Fix formatting and styling details ( can help with this). Check the deployment preview to see how it looks. -7. Merge and it's automatically published on [posthog.com](/blog) +7. Merge and it's automatically published on [posthog.com](/blog). Once published, you can share it on social ([LinkedIn](/handbook/content/linkedin), X, Bluesky, etc.), with relevant coworkers, and in relevant communities (like HackerNews, but be careful not to spam or ask for upvotes). This might feel a little cringe, but it's critical for actually getting people to read your writing. diff --git a/contents/handbook/engineering/writing-docs.md b/contents/handbook/engineering/writing-docs.md index 6004ac82b5d8..ec45358fe4dc 100644 --- a/contents/handbook/engineering/writing-docs.md +++ b/contents/handbook/engineering/writing-docs.md @@ -90,3 +90,4 @@ For an example, see the [PostHog AI `README`](https://github.com/PostHog/posthog - [What nobody tells developers about documentation](/newsletter/what-nobody-tells-devs-about-docs) - [Docs style guide](/handbook/docs-and-wizard/docs-style-guide) - [PostHog style guide](/handbook/content/posthog-style-guide) +- [Writing blogs as an engineer](/handbook/engineering/writing-blogs) From 658d72ae478ddf9ca97d50524f15785ebf52f1e6 Mon Sep 17 00:00:00 2001 From: Ian Vanagas <34755028+ivanagas@users.noreply.github.com> Date: Fri, 5 Jun 2026 15:52:45 -0400 Subject: [PATCH 3/3] add a linky --- contents/handbook/company/goal-setting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contents/handbook/company/goal-setting.md b/contents/handbook/company/goal-setting.md index be08726bce9e..3e2aa382894b 100644 --- a/contents/handbook/company/goal-setting.md +++ b/contents/handbook/company/goal-setting.md @@ -63,7 +63,7 @@ What themes can we distill from the above HOGS list? What are categories of thin ### Other things to consider -- For engineering teams - did you do anything cool last quarter that other engineers could learn from? Consider adding a goal to write about those things on our company blog! +- For engineering teams - did you do anything cool last quarter that other engineers could learn from? Consider adding a goal to [write about those things on our company blog](/handbook/engineering/writing-blogs)! - Have you done a pricing review for this product in the last year? If not, follow our [RFC template](https://github.com/PostHog/requests-for-comments-internal/blob/main/_TEMPLATES/request-for-comments-pricing-review.md) to do a pricing review this quarter. ## New goals (15 minutes - do as a team)