Writing Great Announcements
Your changelog is a direct line to your users. Here’s how to make the most of it.The anatomy of a great announcement
[TODO: ADD IMAGE - ANNOTATED SCREENSHOT OF A WELL-STRUCTURED ANNOUNCEMENT]1. Title
Your title is the first thing users see. Make it count. Do:- Be specific: “Export reports to PDF”
- Lead with the benefit: “Faster page loads”
- Use action words: “New”, “Introducing”, “Now available”
- Be vague: “Updates” or “New feature”
- Use version numbers alone: “v2.4.1”
- Be too long: Keep it under 60 characters
2. Opening line
Hook readers in the first sentence. Get to the point immediately.3. Body content
Structure your content for scanning:- Use headings to break up sections
- Use bullet points for lists of changes
- Use bold text for key information
- Keep paragraphs short — 2-3 sentences max
4. Visuals
A picture is worth a thousand words. Include:- Screenshots for UI changes
- GIFs for interactive features
- Code snippets for API updates
- Before/after comparisons
Writing for different announcement types
- New Features
- Improvements
- Bug Fixes
Goal: Get users excited and show them how to use it.Structure:
- What it is (one sentence)
- Why it matters (the benefit)
- How to use it (steps or link)
- What’s next (optional)
Rich text editor features
The updates.page editor supports:| Feature | Shortcut | Description |
|---|---|---|
| Bold | ⌘+B | Bold text |
| Italic | ⌘+I | Italic text |
| Heading 1 | ⌘+⌥+1 | Main section headers |
| Heading 2 | ⌘+⌥+2 | Subsection headers |
| Bullet list | ⌘+⇧+8 | Unordered lists |
| Numbered list | ⌘+⇧+7 | Ordered lists |
| Code | ⌘+E | Inline code |
| Code block | ⌘+⌥+C | Multi-line code |
| Link | ⌘+K | Add hyperlinks |
| Quote | ⌘+⇧+B | Blockquotes |
Adding images
Click the image icon in the toolbar or drag and drop directly into the editor. Supported formats: PNG, JPG, GIF, WebP [TODO: ADD GIF - DRAGGING IMAGE INTO EDITOR]Adding videos
Click the video icon and paste a YouTube or Wistia URL. The video will embed automatically.Writing tips from the pros
Write for scanners
Write for scanners
Most users won’t read every word. Make key information impossible to miss with bold text, headings, and bullet points.
One announcement, one topic
One announcement, one topic
Don’t bundle unrelated updates. Users should know exactly what an announcement is about from the title.
Link to more details
Link to more details
Keep announcements concise. Link to docs, blog posts, or help articles for users who want to go deeper.
Be human
Be human
It’s okay to show personality. Thank users, admit mistakes, get excited about wins.