Confluence Essentials
Confluence Cloud Best Practices
.svg)
Confluence Use Cases
Confluence News
Documentation Guide
Author: Create Content That’s Easy to Read
Steffen Burzlaff
author |
|---|
Welcome to the second step in the Content Lifecycle! Every piece of content goes through a journey, and in this phase, we focus on how to write clear, structured, and reader-friendly content. If you haven’t checked out Step 1: Plan, we recommend starting there.
Writing Doesn’t Have to Be Scary!
The best content is short, clear, and helpful. Think of your pages like an instruction manual for your reader – what would you want to know if you were them?
By prioritizing clarity, structure, and readability, you’ll create content that’s easy to use and maintain. In this article, we’ll cover:
The Sender and Receiver Concept: Understanding your audience.
How to Structure Content Effectively: Making information easy to follow.
How to Make Your Content Lovable: Keeping it engaging and useful.
Like in Step 1, we’ll use our fictional SaaS company Good Software as an example. Let’s dive in!
The Sender and Receiver Concept
Communication is never one-way! There’s always a sender and a receiver. When Good Software writes documentation, it may feel like they’re just pushing information out. But on the other side, there’s always a person reading, interpreting, and acting on it.
🧐 Always ask yourself: Who am I writing for? Different audiences need different levels of detail.
For example, if Good Software launches a new search filter, here’s how they might explain it:
Engineers on the Team
“The new search filter leverages an advanced indexing system using Elasticsearch, improving response times by 30%. Here’s how we adjusted the ranking algorithm…”
The Organization
“Users can now find content in seconds, reducing frustration and improving productivity. Support teams can help customers troubleshoot faster, and marketing can highlight this as a key efficiency boost.”
Customers
“Need to find content quickly? Our new search filter lets you narrow down results instantly. Just type in what you need!”
Tailoring content to your audience makes all the difference!
Structuring Your Content Effectively
Before writing, always consider your structure. A good outline saves time and makes content easier to digest. Not sure where to start? Here are two common structures we can recommend:
Pyramidal Structure: Start with the most important information first, then add supporting details.
Funnel Structure: Begin with broad context, then narrow down to specifics.
How should you apply them?
🔺 Use pyramidal structure for: How-to guides, release notes, API documentation.
🔻 Use funnel structure for: Feature descriptions, troubleshooting articles, storytelling.
📌 Pro tip: Start with an outline and check if it makes sense before diving into the full article!
Learn more about these concepts in the Minto Pyramid.
Make Your Content Easy to Scan
Most readers skim rather than read every word. Here’s how to make scanning easier:
Use Headings & Subheadings: Mind-blowing tip, right? But seriously! Apply them as much as is necessary. And don’t be afraid to user smaller headings (H4, H5, even H6), especially when specific content needs more emphasis.
Break Text into Lists: Bullet points make key takeaways pop – like this list you’re currently reading!
Write Short Paragraphs: Short content makes it more digestible for your reader. Aim for 2–3 sentences max per paragraph.
Best Practices When Formatting Your Content
Structuring content is just half the battle. Formatting your content is the other half. If you’re content isn’t readable because of bad formatting, you’re Confluence offers plenty of features to make content more readable:
✨ Formatting Options: Headers, layouts, and bullet points to break up text.
🧠 Use AI: Helps rewrite, reformat, and improve clarity.
📊 Dynamic Content: Embed tables of contents, expandable sections, and more!
Learn how to create beautifully styled and formatted pages in Confluence.
3 Quick Writing Tips
When writing content make sure to keep a clear and friendly tone. Here are some tips to remember:
Write like you’re explaining to a teammate over coffee. Avoid jargon and ambiguous abbreviations!
Keep it short and action-oriented. Say only what’s necessary.
Focus on what the reader needs to do. Be clear and direct.
Using Confluence
Atlassian Intelligence can help refine your writing by adjusting tone and voice or making content more concise. AI is only available with the premium and enterprise plan of Confluence. If you don’t have access to Atlassian Intelligence, you can try Rovo, a separate Atlassian product that brings a ChatGPT-like assistant directly into your Confluence site.
Learn how to use Atlassian Intelligence to boost your team efficiency.
Enhance with Visuals
A well-placed image or macro makes content much easier to follow!
Screenshots: Show, don’t just tell! This clarifies steps and reduces ambiguity.
Diagrams: Simplify complex ideas.
Dynamic Content: GIFs, videos, and interactive elements keep users engaged.
Using Confluence
Macros make Confluence an even more powerful tool, allowing you to embed dynamic content like tables of contents, expandable sections, and more. You can visualize data with charts or create detailed diagrams using apps like Gliffy or Draw.io.
Learn more about using charts in Confluence.
Reuse Content Instead of Duplicating It
Instead of copying and pasting content across multiple pages, reuse it dynamically.
For example, rather than repeating a product description across 10+ pages, Good Software keeps it in a central location and references it elsewhere. If the description changes, they update it once, and it updates everywhere!
Using Confluence
The Excerpt Macro in Confluence allows you to store key information in a central place for easy reuse. To include content from another page, use the insert excerpt macro. This simple yet powerful approach helps maintain consistency across pages. You can take it a step further by:
Using IDs within the Excerpt Macro to pull in specific information with even greater precision. This approach is perfect for reusing terms, sentences or images.
Creating entire pages and insert them with the include page macro into another one. We recommend using this when you want to reuse rich content like tables, charts or other more complex content.
Learn how to reuse content in Confluence.
Using Apps for Confluence
Scroll Documents for Confluence makes it easy to reuse entire pages and integrate them seamlessly into your documentation. This helps keep your content structured and up to date without extra effort.
Wrap-Up: Writing Great Content is About Connection
Great content isn’t just well-written; it’s reader-friendly, structured, and engaging. By focusing on clarity, conciseness, visuals, and audience needs, you’ll create content that’s easy to use and maintain.
Now, we’d love to hear from you!
💬 How do you approach writing documentation?
📢 What strategies help you keep content clear and engaging?
🔄 Have you tried any of these techniques in Confluence?
Drop a comment below and share your thoughts! If you found this article helpful, share it with your team or on social media. Let’s make content creation easier for everyone.
