Tips before writing your first newsletter (#15161)

* tips before writing a newsletter

* Update newsletter-tips.md

Removed a couple of more process-related sections comparing newsletters and blogs, and added a closing note of encouragement.

* Homepage feature flag (#15162)

* getFeatureFlag

* freshen things up

* feat(docs): add react-native manual session controls (#15151)

* feat(docs): add react-native manual session controls

* fix: add replay plugin version

* docs: replace deprecated PII hashing template with Hash properties template (#15166)

The PII Data Hashing template (template-pii-hashing) has been hidden in
favor of the Hash properties template (template-hash-properties) which
also handles $set/$set_once properties. Consolidates the two bullet
points into one referencing the recommended template.

Ref: PostHog/posthog#48422

Co-authored-by: inkeep[bot] <257615677+inkeep[bot]@users.noreply.github.com>

* chore(deps): Update @posthog/types to 1.352.0 (#15168)

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* onboarding conversations playbook created (#15172)

* onboarding conversations page created

* Corrected headings

* heading correction

* docs(llm-analytics): update BYOK settings link to new global settings path (#15174)

PR PostHog/posthog#48565 moved LLM analytics BYOK settings from
/llm-analytics/settings to the global Settings page. Updated the
evaluations docs to point to the canonical new location and use
the style guide convention for nested UI element references.

Co-authored-by: inkeep[bot] <257615677+inkeep[bot]@users.noreply.github.com>

* docs: document insight picker modal for creating endpoints from insights (#15163)

Reflects changes from PostHog/posthog#47902. Users can now create
insight-based endpoints directly from the Endpoints page via
New endpoint > Insight-based endpoint, in addition to the existing
method from an insight's three-dot menu. Also fixes definition list
style to use dashes per style guide.

Co-authored-by: inkeep[bot] <257615677+inkeep[bot]@users.noreply.github.com>

* Blog: The best Datadog alternatives & competitors, compared (#15157)

* best datadog alternatives

* Import dynatrace

* assorted fixes

* Apply suggestions from code review

Co-authored-by: Natalia Amorim <natalia@posthog.com>

* update otel point

---------

Co-authored-by: Natalia Amorim <natalia@posthog.com>

* Update Unleash (#15177)

* Onboarding conversations page update (#15178)

* Corrected headings
* src nav update

* Update lead-scoring formatting.md (#15122)

A small tweak to disambiguate the new business list

* add: handbook updates for content writer agent (#15091)

* add: handbook updates for content writer agent

* duplicate index

* correct name

* update links

* small edits and add screenshots

---------

Co-authored-by: Edwin Lim <edwin@posthog.com>

* update wizard docs (#15165)

* update wizard docs

* more frameworks and tweaks

* vale updates

* fixes

* Refactor onboarding conversations playbook formatting (#15180)

Styling changes: Updated headings and improved formatting for clarity in the onboarding conversations playbook.

* Clarified where incident comms for GTM should happen (#15179)

* Update one line open source FF article (#15181)

* Fix incoming change that wasnt merged (#15185)

* bring back the people map (#15182)

* docs(llm-analytics): mention provider key error warning banners on evaluations page (#15184)

Reflects PR #48512 which surfaces BYOK provider key failures directly on the evaluations list and individual evaluation pages with warning banners.

Co-authored-by: inkeep[bot] <257615677+inkeep[bot]@users.noreply.github.com>

* docs: Document trailing slash stripping for exact URL matching (#15188)

## Changes

Documents the trailing slash stripping behavior for exact URL matching in product tours and surveys, based on [PostHog/posthog#48497](PostHog/posthog#48497).

### Updated files

- **`contents/docs/product-tours/targeting.mdx`** – Added a note after the URL conditions table explaining that trailing slashes are stripped from both URLs when using exact matching.
- **`contents/docs/surveys/creating-surveys.mdx`** – Added a clarification to the URL targeting bullet point in Display conditions that trailing slashes are stripped for exact matching. Also fixed a missing Oxford comma.

### Context

PR #48497 added a UI clarification message in the product tour configuration that appears when "Exact" URL match type is selected: "Trailing slashes are stripped when matching exact URLs." Since surveys share the same URL matching infrastructure (`SurveyMatchType`), both docs pages are updated to reflect this behavior.

* update tutorials to use latest flags stuff (#15191)

* Specify base salary in probation period terms (#15143)

* docs: Add sentiment classification to LLM Analytics docs (#15195)

* docs(llm-analytics): add sentiment classification section to traces page

Documents the new on-demand sentiment classification feature from
PostHog/posthog#48277. Sentiment classifies user messages in traces
as negative/neutral/positive using a local ONNX model.

* docs(llm-analytics): add sentiment classification section to generations page

---------

Co-authored-by: inkeep[bot] <257615677+inkeep[bot]@users.noreply.github.com>

* docs(product tours): Update docs for draft auto-save system (#15192)

## Changes

Updates product tours documentation to reflect the new draft auto-save system introduced in [PostHog/posthog#48393](PostHog/posthog#48393).

### What changed in the product

Product tours now use a draft system when editing:
- Changes auto-save as you edit with status indicators (unsaved/saving/saved)
- Click **Save** to publish changes or **Cancel** to discard the draft
- If you close your browser with unpublished changes, a banner appears with options to continue editing or discard
- The toolbar and main app stay in sync automatically

### Files updated

- **`contents/docs/product-tours/creating-product-tours.mdx`** – Updated the "Save and launch" section to describe auto-save behavior and the publish/discard workflow.
- **`contents/docs/product-tours/managing-tours.mdx`** – Updated the "Editing live tours" section to clarify that changes save to a draft first (not published immediately) and document the unsaved changes banner.

* Added a link to my planning issue (#15167)

* chore(deps): Update @posthog/types to 1.352.1 (#15201)

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* docs: Document SQL/HogQL querying capability for MCP (#15063)

* docs(mcp): add SQL and HogQL queries section for AI agents

Document the new query-data SQL skill that enables AI coding agents
to execute HogQL queries against PostHog data. This includes querying
system data (feature flags, cohorts, insights, etc.) and analytics
data (events, persons, sessions).

Related to PostHog/posthog#46948

* docs(ai-engineering): Update MCP description to include HogQL querying capability

Reflects the new SQL skill added in PR PostHog/posthog#46948 that enables AI agents to query PostHog data using HogQL.

---------

Co-authored-by: inkeep[bot] <257615677+inkeep[bot]@users.noreply.github.com>

* docs(funnels): Document inline events for funnel steps (#15139)

* docs: add inline events documentation for funnels

Reflects PR #48075 which adds inline events UI support for funnels,
allowing users to combine multiple events into a single funnel step.

* Add screenshots

---------

Co-authored-by: inkeep[bot] <257615677+inkeep[bot]@users.noreply.github.com>
Co-authored-by: Georgis Andonis <georgis@posthog.com>

* handbook: add step to unassign yourself in Vitally on account handover (#15206)

Adds guidance for outgoing account owners to unassign themselves from the
account in Vitally after completing a handover, ensuring clear ownership.

* docs(experiments): Add AI session replay summarization feature (#14909)

Co-authored-by: inkeep[bot] <257615677+inkeep[bot]@users.noreply.github.com>
Co-authored-by: Sarah Sanders <88458517+sarahxsanders@users.noreply.github.com>

* Add Interview questions video to website (#15205)

* adding video to pages

* create blog post for video

* Update startup-interview-questions.md

* Update startup-interview-questions.md

* add notes + workaround for anonymous person handling in export (#15204)

* Adding myself in the byline + adding CTA at the bottom (#15189)

* docs: Add ticket recovery documentation for Support widget and JavaScript API (#15194)

* docs(support): add ticket recovery across browsers section to widget docs

Documents the new "Recover your tickets" feature from PR #48509 that allows
end users to restore their support tickets when switching browsers via an
email-based recovery link.

* docs: add ticket recovery API methods (requestRestoreLink, restoreFromUrlToken)

---------

Co-authored-by: inkeep[bot] <257615677+inkeep[bot]@users.noreply.github.com>

* docs(support): add message status indicators documentation (#15017)

Document the new Sent/Read status indicators for customer messages
added in PostHog/posthog#47842. Support agents can now see whether
their messages have been delivered and read by customers.

Co-authored-by: inkeep[bot] <257615677+inkeep[bot]@users.noreply.github.com>

* docs(experiments): document ending experiments when variant already shipped (#15176)

* docs: document ending experiments when variant already shipped (PR #48517)

Update analyzing-results.mdx to reflect that the End experiment button
is now always available when an experiment has results, even if a variant
has already been shipped to 100%. In that case, the experiment ends
without modifying the feature flag.

* Update notes on ending experiments with feature flags

Remove redundant note, we already mention the same thing below

---------

Co-authored-by: inkeep[bot] <257615677+inkeep[bot]@users.noreply.github.com>
Co-authored-by: Joshua Ordehi <45109738+ordehi@users.noreply.github.com>

* missing backtick (#15211)

* Update feature ownership (#15203)

* Endpoints product page (#15132)

* endpoints playground component

* first pass at endpoints content

* added endpoints playground to slide

* content

* scenarios

* autosize

* WRITE your query

* endpoints content

* remove dupe menu

* Merge branch 'master' into endpoints-test

* endpoints polish

* updated screenshots

* updated description

---------

Co-authored-by: Eli Kinsey <eli@ekinsey.dev>
Co-authored-by: Abheek Basu <abe@posthog.com>

* Remove beta callout from trace summarization docs (#15217)

The Summary tab in LLM analytics traces is no longer in beta,
as reflected by the removal of the beta tag in PostHog/posthog#48738.

Co-authored-by: inkeep[bot] <257615677+inkeep[bot]@users.noreply.github.com>

* docs: Add account deletion details and data retention info (#15216)

## Changes

Added comprehensive documentation for account deletion process. Enhanced the account settings page with detailed information about what happens when users delete their accounts, including immediate account removal and 30-day data clearing timeline. Added a new row to the data deletion table in the privacy documentation to include account deletion as an option with direct links to relevant settings and documentation.

## Checklist

- [ ] I've read the [docs](https://posthog.com/handbook/docs-and-wizard/docs-style-guide) and/or [content](https://posthog.com/handbook/content/posthog-style-guide) style guides.
- [ ] Words are spelled using American English
- [ ] Use relative URLs for internal links
- [ ] I've checked the pages added or changed in the Vercel preview build 
- [ ] If I moved a page, I added a redirect in `vercel.json`

* docs: Add Conversations workflow actions documentation (#14939)

* docs(workflows): add Conversations actions section for ticket management

Documents the new Get ticket and Update ticket workflow actions added in PR #47277.
Includes:
- Action descriptions and available options
- Example automation use cases
- Conversation event triggers reference

* docs(support): add workflow trigger events section for PR #47277

Document new server-side events emitted when ticket/message state changes:
- $conversation_ticket_created
- $conversation_ticket_status_changed
- $conversation_ticket_priority_changed
- $conversation_ticket_assigned
- $conversation_message_sent
- $conversation_message_received

These events enable automation scenarios via workflows.

* docs(support): add workflow automation section to getting started guide

Adds a new QuestLogItem documenting how to automate ticket management using Workflows. This covers the new conversation events ($conversation_ticket_created, $conversation_ticket_status_changed, $conversation_message_received) and workflow actions introduced in PR #47277.

* Fix formatting in persons model note documentation

* Fix formatting in persons model note

* docs: Add Properties column to workflow trigger events table per review feedback

* fix: Add blank lines in OSButton for proper MDX rendering

* Add separate Properties columns to Conversations actions and event triggers tables

* Revert accidental changes to persons-model-note.mdx snippet

---------

Co-authored-by: inkeep[bot] <257615677+inkeep[bot]@users.noreply.github.com>
Co-authored-by: Alex V <alexander.veryaysky@gmail.com>
Co-authored-by: Alex V <aleks@posthog.com>

* docs: add persons list section with last seen column documentation (#15212)

Reflects PR #47757 which adds a Last seen column to the persons list.
- Document default persons list columns including new Last seen column
- Note that last seen updates hourly and shows "last hour" for recent activity
- Fix in-app URLs to use app.posthog.com per style guide

Co-authored-by: inkeep[bot] <257615677+inkeep[bot]@users.noreply.github.com>

* open links in new windows (#15220)

* remove posthog ai from people page (#15197)

* added romania flag (#15225)

* docs(dashboards): update mobile layout note to reflect removal of separate xs layout (#15159)

The separate mobile (xs) layout was removed in PostHog/posthog#47682. The mobile layout is now automatically derived from the desktop layout by stacking tiles vertically, and layout editing (drag and resize) is disabled on narrow viewports.

Co-authored-by: inkeep[bot] <257615677+inkeep[bot]@users.noreply.github.com>

* get rid of beta tag on endpoints product page (#15226)

* revised preamble to make purpose and context clearer

* Update contents/handbook/content/newsletter-tips.md

Co-authored-by: Ian Vanagas <34755028+ivanagas@users.noreply.github.com>

* add to nav bar

---------

Co-authored-by: Eli Kinsey <eli@ekinsey.dev>
Co-authored-by: Ioannis J <yiannis@posthog.com>
Co-authored-by: inkeep[bot] <257615677+inkeep[bot]@users.noreply.github.com>
Co-authored-by: posthog-js-upgrader[bot] <248546023+posthog-js-upgrader[bot]@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Magda Olszewska <magda@posthog.com>
Co-authored-by: Ian Vanagas <34755028+ivanagas@users.noreply.github.com>
Co-authored-by: Natalia Amorim <natalia@posthog.com>
Co-authored-by: Ben Bradley <38007189+bendbradley@users.noreply.github.com>
Co-authored-by: Sarah Sanders <88458517+sarahxsanders@users.noreply.github.com>
Co-authored-by: Edwin Lim <edwin@posthog.com>
Co-authored-by: Simon Fisher <simon@posthog.com>
Co-authored-by: Dylan Martin <dylan@posthog.com>
Co-authored-by: Fraser Hopper <fraser@posthog.com>
Co-authored-by: SaraMiteva <sara@posthog.com>
Co-authored-by: Georgis Andonis <georgis@posthog.com>
Co-authored-by: danazou <52993274+danazou@users.noreply.github.com>
Co-authored-by: Andy Vandervell <92976667+andyvan-ph@users.noreply.github.com>
Co-authored-by: Luke Belton <58511679+luke-belton@users.noreply.github.com>
Co-authored-by: Joshua Ordehi <45109738+ordehi@users.noreply.github.com>
Co-authored-by: Cory Watilo <corywatilo@gmail.com>
Co-authored-by: Abheek Basu <abe@posthog.com>
Co-authored-by: Rafael Audibert <32079912+rafaeelaudibert@users.noreply.github.com>
Co-authored-by: Alex V <alexander.veryaysky@gmail.com>
Co-authored-by: Alex V <aleks@posthog.com>
Co-authored-by: Abheek Basu <abheek94@gmail.com>

Author: 25 people

contents/handbook/content/newsletter-tips.md

@@ -0,0 +1,161 @@
+---
+title: Tips for new writers
+sidebar: Handbook
+showTitle: true
+---
+
+PostHog has unusually high editorial standards (especially for a B2B SaaS company). When I first started writing here, I struggled quite a bit. The feedback was good, but it was a lot, and for a while I couldn't tell if I was actually getting better or just spinning my wheels.
+
+This handbook page is all the stuff I would tell myself from back then if I could. I wrote it for any future writers who join our editorial team. (It might also be useful for anyone trying to understand our unique developer content marketing and style more deeply.) It won't make the learning curve disappear, but hopefully makes it easier! 
+
+## Before you write anything
+
+Remember that you are new. Learning how to do any creative skill in a specific style takes time. Even the most talented writer in the world would make mistakes adopting PostHog's voice. As the wise old saying goes, "sucking at something is the first step towards being sorta good at something." 
+
+Don't compare your ramp-up speed to peers or people who've been here longer. Comparison is almost meaningless because everyone here has wildly different backgrounds It's why you were hired; it makes us better as a team. You have your own strengths and experiences, so make use of them.
+
+While things are still relatively chill early on, read and absorb as much PostHog content as you can: blogs, newsletters, the handbook. Fix typos or update things as you go. Small PRs are genuinely appreciated and noticed.
+
+> **Bonus tip:** Keep a daily work journal. The random thoughts, questions, and observations you have as you're onboarding will make for great material later on. Even this guide is based on my notes from onboarding.
+
+---
+
+## Timeline expectations for your first newsletter
+
+A lot of people underestimate how much work it takes to write a genuinely good newsletter.
+
+Experienced writers (i.e., people who've been doing this at PostHog for years) take about **2 weeks end-to-end** to ship a great newsletter. That includes outlining, drafting, and 2–3 rounds of review to get to the finished piece (plus time juggling other projects in between).
+
+As someone new, expect it to take longer. My first newsletter took me about 4–6 weeks:
+
+- 1 week purely on the outline
+- 5-8 rounds of feedback (shorter toward the end) spread over 2-3 weeks
+- The last stretch was tiny edits and infographics over 1 week
+- You will get sick of writing it. That's normal, too.
+
+At the end, I didn't personally feel like my first newsletter was amazing, even though I was told it was very solid. Like I said earlier, remember it takes time to adapt to a new style for creative work.
+
+**To keep from going insane, have 1–2 smaller shippable projects running alongside the newsletter.** In my first month, I tunneled on just the newsletter because it felt like The One Thing I had to do to prove to myself I could do this. In hindsight, putting all my confidence eggs in one basket added a lot of unnecessary pressure and honestly dampened my creativity. A blog refresh, smaller SEO post, along with handbook edits in parallel gives you breathing room. The early wins and visibility on the team are a real bonus, too.
+
+---
+
+## The #1 guiding principle when writing here
+
+Make it second nature to constantly ask yourself: *"What do I want the reader's reaction to this piece to be?"*
+
+For example: *"I want to challenge their assumptions and make them feel surprised."*
+
+Charles' [Collaboration sucks](/newsletters/collaboration-sucks) article is a great example. It was right on the edge of clickbaity, enough for someone to comment "I was expecting to be annoyed but then I read it and was like, okay."
+
+That's the goal. This one question should drive your title, your headings, your tone, your pacing — everything, really. A "How to do X" [title](/handbook/content/newsletter#title) can almost always be turned into something that makes a person *feel* something.
+
+This matters most for newsletters, but it applies to everything we write. Our distinguishing factor is that we always have an opinion, a flair, a point of view. Without that, we'd become so bland, so fast.
+
+---
+
+## Coming up with ideas
+
+Ideas come from anyone and anywhere. A lot of times, conversations that happen in all-hands or Slack can be the inspiration for a blog. Basically, whatever you think might be interesting is game – you were hired as a developer who likes writing, so you have the advantage of already somewhat knowing our ICP's interests.
+
+Even when you are new, don't let content ideas live inside your head. Turn them into a GitHub issue as soon as possible. Before you commit to writing something (including your first newsletter), have 2–3 issues with some preliminary research already done so you can make a more informed choice about what to actually write.
+
+Not all ideas are good. Many ideas will die, fizzle out, or get picked up again later.
+
+---
+
+## How to write for our readers
+
+Writing nonfiction is a user-centered design problem. You have to start with: *who is this for?*
+
+Our newsletter has three main reader groups:
+
+- **Product engineers** — developers who also own product work at startups
+- **Technical founders** — CEOs of early startups with technical or product backgrounds
+- **Software engineers** — not always our ICP, but developers who are curious about broadening their knowledge of product and startup culture (think: a SWE at a big tech company who wonders what else is out there)
+
+Every article should naturally appeal to at least one of these groups — ideally all three, but that's not always possible.
+
+Once you know your reader, make sure the intro and headline appeal to them immediately. The hook should answer: *why should an engineer care?*
+
+Don't narrow the audience too much, but don't be so broad that you capture nobody. And note that the most compelling hook for your audience might not be the most interesting one for *you* to write and that's okay.
+
+For example, when I was writing my first newsletter, [10x job posts for 10x engineers](/newsletter/10x-job-posts), I first kept gravitating toward hooks like "recruiting is so hard" or "we've all read boring job ads." Those were fun and interesting to write, but none of them were actually that targeted for any of the three audiences.
+
+I realized that the best audience was technical founders who want to hire great talent early on, so I ended up opening with "your company is only as good as your people". It's a line that's been said a million times and I personally found a little dull. But it was highly effective for technical founders.
+
+(Think of choosing a hook like choosing a character in a fighting game: sometimes your second-highest DPS character is the best pick because they do physical damage, and the enemy has a lot of magic resistance.)
+
+You can also angle for one group first but weave in relevance for others. For example, the [10x job posts](/newsletter/10x-job-posts) piece was aimed at founders, but by telling them what to look for when hiring great engineers, it was also implicitly signaling to the product engineers and SWEs reading it what traits they should aspire to have themselves while job searching and interviewing.
+
+A few smaller principles worth keeping in mind:
+
+- Avoid double intros. Pick one good hook and then get right into the content.
+- Never say "it depends". If you're leaning that way, it usually means you need to go straight to examples
+- Paint the problem, then get to "how to deal with it" as early as possible. Developers want the useful part fast.
+- The line between funny and cringe is very easy to cross.
+- Don't lean on big enterprise company examples unless it genuinely fits the piece. It usually won't.
+- Snark and strong opinions are good. Pure negativity is not.
+
+---
+
+## How to actually write a newsletter
+
+**The biggest lesson I learned was that writing a newsletter is 80% research, 20% writing.**
+
+What sets PostHog content apart is that we actually do the work. We don't just say what we think, we actually go and find out.
+
+In other words, we gather evidence usually in the form of (1) real-world examples or (2) first-hand experience to establish credibility.
+
+**Real-world examples** are observed data from other companies, blogs, and people — and this is what you'll lean on most as a writer. Research examples first. They don't just support your outline; they *are* the foundation of it. You might have a strong opinion and feel certain it's right, but you don't actually know until you go find out.
+
+For example, for the [10x job posts newsletter](/newsletter/10x-job-posts), the "data" I used to develop my opinion were literally job posts from other companies.
+
+You should include real examples even during your outline phase because without them, you don't actually have an informed opinion to build on yet.
+
+Where to find good examples:
+
+- [exa.ai](http://exa.ai/) — an AI search engine that's much better than ChatGPT for surfacing real examples (ChatGPT has a tendency to give you plausible-sounding examples that are just made up)
+- [First Round Review](https://review.firstround.com/)
+- [HN Algolia search](http://hn.algolia.com/) — the comments can be just as useful as the posts themselves
+- Slack search for what PostHog people have actually said about the topic
+- GitHub — past PRs and issues at PostHog
+
+Avoid using other blog posts as your primary source material. Basic digital literacy. "I saw it on the internet" or "I made that shit up" is not a valid source.
+
+**First-hand experience** is more like "things we've learned at PostHog." Charles can write [a piece](/newsletter/how-i-get-good-advice) that's mostly just his perspective because he has the experience and credibility as an exec — he'll almost always open with a personal anecdote or something from PostHog's history to establish that.
+
+As a writer, you probably don't have that kind of experience to lean on yet, but you can do this too by framing things as "what we've learned at PostHog". I do this by reading all past PostHog content on a topic before I start writing, and then pulling out the real internal perspectives and examples. (Conveniently, you can save those to put in as internal links later!)
+
+---
+
+## When your writing doesn't feel good
+
+A useful gut-check: *would someone who knows a lot about this topic share this with someone else?* Worth noting that this person might not be the same as your target reader. For the [10x job posts](/newsletter/10x-job-posts) piece aimed at technical founders, the person who'd actually share it is more like a seasoned recruiter or someone on a talent team.
+
+If the answer is no, here's a quick diagnostic list:
+
+- **The topic feels overdone and unoriginal.** That's okay, originality isn't really the goal. Your goal is to write something that genuinely moves *this* audience at *this* time.
+- **We've written about something too similar to this in the past.** Also fine. Nobody remembers something we published two years ago. We commonly refresh old blogs into newsletters because the structure and style naturally evolves it into something different
+- **It's too clickbait-y or fluffy.** You probably need to go one level deeper. If it feels fluffy, it means you're not even convinced by your own argument. Find more concrete examples to back up your opinion.
+- **It's getting dry and boring.** It probably needs a stronger take. Talk to people with real experience on the subject. For example, when I was writing the "WTF does a PM do?" piece, I asked PMs directly what they thought were the most important parts of the role, and what made for a bad PM. That made it so much better.
+- **The content is interesting but isn't flowing well.** Rewrite it, then rewrite it again. When I was stuck on the intro for "WTF does a product manager do?", I wrote three completely different versions, then wrote out a pros/cons list of what I liked and disliked about each before deciding.
+- **It's too deep and detailed.** Try zooming out. Ask yourself "why would anyone actually read this?" Most of our newsletter topics hover at a certain level of detail. For example, we've written "An engineer's guide to talking to users," but we haven't written "An engineer's guide to dealing with difficult customers on quick calls." If the topic feels too niche, reconsider the scope (You'll probably also struggle to find enough examples for it.)
+- **I can't figure out what's wrong, I just know it is.** Ask for help — especially in your first few pieces. I asked Ian to write an entire section for my newsletter because I just needed to move on at a certain point.
+- **I tried all of the above and it still just feels forced.** The topic might just not be working. Depending on how deep you are, it might be worth pivoting rather than pushing through. You might just save it for a later issue.
+
+---
+
+## When you hit writer's block
+
+Writer's block is real and it will happen. It usually isn't actually about the writing — for me it's almost always anxiety or self-doubt in disguise. Things that helped me:
+
+- Change your environment. Go work at a cafe or outside for a bit. Especially since we work fully remote, getting out of the house makes a huge difference.
+- Switch to a different project. Something more tactical and less creative helps reset things and give you a little boost.
+- Brain dump — stream of consciousness, no editing, just write it. Even if you don't use the output later, it's like a nice warm-up exercise.
+- If your stuckness is rooted in self-doubt, try all of the classic self-care and self-compassion tips. Journaling, exercise, or whatever works for you. Staring at the doc rarely fixes anything for me, personally.
+
+---
+
+Things click eventually, but might just take longer than you'd expect. As always, don't hesitate to ask for help and feedback from the rest of the editorial team along the way. We want you to succeed!
+
+– <TeamMember name="Jina Yoon" />

src/navs/index.js

@@ -683,6 +683,10 @@ export const handbookSidebar = [
                         name: 'Overview',
                         url: '/handbook/content/newsletter',
                     },
+                    {
+                        name: 'Tips for new writers',
+                        url: '/handbook/content/newsletter-tips',
+                    },
                     {
                         name: 'Newsletter ads',
                         url: '/handbook/content/newsletter-ads',