Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Handbook: Update writing for PostHog #9388

Merged
merged 2 commits into from
Sep 19, 2024
Merged

Handbook: Update writing for PostHog #9388

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d7c0337
update writing for posthog
ivanagas Sep 19, 2024
de9736e
add back the em dashes
ivanagas Sep 19, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 30 additions & 29 deletions ...k/growth/marketing/writing-for-posthog.md → .../growth/marketing/writing-for-posthog.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,15 +14,15 @@ Good writing is subjective, but it helps to have some common themes. At PostHog,

- **Is it opinionated?** Not all articles are opinions, but all our work should be _opinionated_. Don't sit on the fence. It's better to be slightly wrong, or controversial, than say nothing.

- **Does it pass the Neil test?** Neil (@neilkakkar) is a real product engineer on the PostHog team, and he reads a lot of content! Do you think your article is something he would find either interesting or useful? If not, you may not be writing something relevant to our target audience. (You do not literally need to ask him to read every piece of content - he is very busy.)
- **Does it pass the Neil test?** <TeamMember name="Neil Kakkar" /> is a real product engineer on the PostHog team, and he reads a lot of content! Do you think your article is something he would find either interesting or useful? If not, you may not be writing something relevant to our target audience. (You do not literally need to ask him to read every piece of content - he is very busy.)

Above all, we write articles, not content.

Our publishing process is something like this:

## Stage 1 – Create an issue / share an idea
## Stage 1 - Create an issue / share an idea

Most articles start life as an idea in the `#content-ideas` Slack channel, or a GitHub issue.
Most articles start life as an idea in the `#content-ideas` Slack channel or a GitHub issue.

Use [this issue template](https://github.com/PostHog/posthog.com/issues/new?assignees=andyvan-ph&labels=content&projects=&template=blog-post-idea-template.md&title=%7Btitle%7D). Add it to the Content & Marketing project board.

Expand All @@ -34,11 +34,11 @@ It's particularly important to figure out what search terms you're targeting if

Ask other team members for feedback on the idea. We rarely say no unless there's a very good reason, but this is an opportunity to refine the idea, headline, and search terms (if applicable).

## Stage 2 – Submitting your first draft
## Stage 2 - Submitting your first draft

All articles should be submitted as Markdown files (*.md) in a pull request (PR) on the [posthog.com repo](https://github.com/PostHog/posthog.com).
All articles should be submitted as Markdown files (*.md or *.mdx) in a pull request (PR) on the [posthog.com repo](https://github.com/PostHog/posthog.com).

You'll need to download GitHub Desktop and Visual Studio Code for this. See [Developing the website](/handbook/engineering/posthog-com/developing-the-website) for how to clone the repo. You don't need a local version of posthog.com as well, but it can be useful.
You'll need to download GitHub Desktop and Visual Studio Code for this. See [developing the website](/handbook/engineering/posthog-com/developing-the-website) for how to clone the repo and run the site locally. You don't need a local version of posthog.com as well, but it can be useful.

New posts should be:

Expand Down Expand Up @@ -90,30 +90,33 @@ tags:

### Folders and URLs

The URL is defined by the `folder` it's placed in and the `filename.md` of the markdown file – e.g. a post in the `founders` folder with the filename `i-love-hedgehogs.md` would have the URL `/founders/i-love-hedgehogs`.
The URL is defined by the `folder` it's placed in and the `filename.md` of the markdown file - e.g. a post in the `founders` folder with the filename `i-love-hedgehogs.md` would have the URL `/founders/i-love-hedgehogs`.

Folders also decide _where_ on the website articles appear.

The main folders are:

- `/contents/blog` – Blog posts
- `/contents/founders` – Articles for the [Founder content hub](/founders).
- `/contents/product-engineers` – Articles for the [Product engineer content hub](/product-engineers)
- `/contents/tutorials` – Tutorials
- `/content/customers` – Customer stories
- `/contents/spotlight` – Startup spotlight
- `/contents/blog` - Blog posts
- `/contents/founders` - Articles for the [Founder content hub](/founders).
- `/contents/product-engineers` - Articles for the [Product engineer content hub](/product-engineers)
- `/contents/tutorials` - Tutorials
- `/content/customers` - Customer stories
- `/contents/spotlight` - Startup spotlight

**Important:** Some articles can rightfully belong in both the founder hub _and_ the product engineers hub. In this case, choose the most appropriate hub folder and then add the `crosspost:` field to your frontmatter so it appears in both. So, add `crosspost: product-engineers` to post a founder's hub article in product engineers as well, and vice versa. You can also add tags from either hub like normal.

### Adding images, short videos and YouTube embeds

Any images or short videos for your article should be uploaded to the appropriate folder under `/contents/images`. Folders include:
Any images or short videos for your article should be uploaded to Cloudinary.

- `/contents/images/blog` – for the blog
- `/contents/images/hubs` – for both content hubs
- `/contents/images/tutorials` – for tutorials
You can do this from posthog.com by clicking on your avatar in the top right, then clicking "Upload media" in the dropdown menu.

![Upload media](https://res.cloudinary.com/dmukukwp6/image/upload/Clean_Shot_2024_09_19_at_08_41_34_931592a275.png)

Copy the link and paste it where you want the image or video to appear in your file.

**Best practices:**

- In most cases, PNGs are the ideal file format. Images are optimized for the web and converted to `webp` automatically. That said, don't upload 4K resolution images. Be sensible.

- Please add a subfolder for your article, so the root folder doesn't become a mess.
Expand All @@ -124,38 +127,36 @@ Any images or short videos for your article should be uploaded to the appropriat

- If your article needs custom artwork, please file a request with Lottie. See: [Art and branding requests](/handbook/design/art-requests) for instructions.

## Stage 3 – Feedback and reviews
## Stage 3 - Feedback and reviews

It's normal for articles to go through at least two rounds of review and amends before being published.

Unless the post is very short, or especially polished, the first round is mainly about high-level feedback. Be clear about areas that need more work, or specific points you want feedback on.

After initial edits, more effort goes into line edits and polish – "production value", structure and flow.

After initial edits, more effort goes into line edits and polish - "production value", structure and flow.

## Stage 4 – Merging and promotion
## Stage 4 - Merging and promotion

Once reviewers have approved the PR, it's ready to merge.

Please actually check the PR checklist – e.g. check you've updated the date before merging, add keywords to the Ahrefs rank tracker if it's an SEO article, etc.
Please actually check the PR checklist - e.g. check you've updated the date before merging, add keywords to the Ahrefs rank tracker if it's an SEO article, etc.

You are responsible for promoting and tracking the performance of your own work.

Consider:
- Posting it in the community Slack
- Sharing it in the #founders-club Slack
- Writing a good tweet
- Sharing it on LinkedIn
- Creating a dashboard of numbers and stuff
- Sharing it in the #founders-club Slack
- Posting it on Hacker News or Reddit (be cautious here)
- Asking other team members to like, share, subscribe etc.
- Asking other team members to smash that like button, share, subscribe etc.
- Purchasing fake traffic from Fiver (don't actually do this)
- Creating a dashboard of numbers and stuff

## Stage 5 – SEO specific admin
## Stage 5 - SEO specific admin

If your article is an SEO piece, remember to add the relevant keywords to the Ahrefs rank tracker, so we can monitor how the page ranks over time.
If your article is an SEO piece, remember to add the relevant keywords to the [Ahrefs rank tracker](https://app.ahrefs.com/rank-tracker/overview/4483813), so we can monitor how the page ranks over time.

If you haven't already, you should also ensure there are internal links pointing to the new page when it's published – see [our SEO guide](/handbook/growth/marketing/seo-guide) for more on that.
If you haven't already, you should also ensure there are internal links pointing to the new page when it's published - see [our SEO guide](/handbook/growth/marketing/seo-guide) for more on that.

> **A short public service announcement from Andy:**
>
Expand Down
Loading