Internal Documentation – Designing Docs Teams Actually Use

[#1]

Webinar Recap: Internal Documentation – Designing Docs Teams Actually Use

Webinar: Internal Documentation: Designing Docs Teams Actually Use

Hi everyone! This article summarizes the key takeaways from our recent webinar, where we explored how to transform messy documentation into a clear and reliable system using Confluence. We covered practical strategies, live examples, and actionable steps for teams.

Key Topics Discussed

Note: All links are for Cloud instances

1. Macros

• Macros are powerful tools in Confluence that help you add dynamic content, automate formatting, and enhance collaboration.

• Examples include Table of Contents, Page Properties, and Task List macros.

• Learn more about Confluence macros

2. Excerpt Macro

• The Excerpt macro lets you define a reusable section of content that can be included on other pages.

• Great for sharing standard information or instructions across multiple pages.

• How to use the Excerpt macro

3. Templates

• Templates help standardize documentation and ensure consistency across your team.

• Use built-in or custom templates for meeting notes, project plans, onboarding guides, and more.

• Explore Confluence templates

Best Practices & Recommendations

• Structure spaces and pages so people can easily find what they need.

• Regularly review and update documentation to keep it relevant.

• Use macros and templates to save time and maintain consistency.

• Encourage team contributions and feedback.

Additional Resources

• New To Confluence? Check Out These Articles

• Confluence User Group

[Andy Gladstone]

Reading the notes while listening to the author speak about this on a webinar is a very meta experience. Thanks for this publish @Tiffany Scolnic! 

[Caity Belta]

Posting some answers to questions we didn't get to during the workshop ⬇️⬇️⬇️

[Caity Belta]

@Joshua Bertrand asked: what is the benefit of using live doc vs a page?

@Tiffany Scolnic answered: Use a Confluence Live Doc when you want fast, real-time collaboration. With a live doc, everyone can edit at once and you don’t have to worry about “who has the latest version.” It’s ideal for things like brainstorms, meeting notes, working drafts, and workshop docs where the content is evolving. Use a regular Confluence page when you need a polished, stable source of truth, like policies, runbooks, and finalized enablement or program docs. A simple rule: if it’s a collaborative workspace, start in a Live Doc and convert to a page once it’s ready to be the official reference.

[Caity Belta]

Eli D. asked: Are there must have automations that every org should have for cleaning up documentation?

@Tiffany Scolnic answered: Yes, there are a few “baseline” automations most orgs should have to keep Confluence clean and trustworthy. First, set up scheduled checks for pages that haven’t been updated in ~6 months to automatically notify owners to review, confirm as still valid, or archive; pair that with an “expiration” label or metadata so you can report on stale content. Second, automate simple workflows like: when a page gets an “archived” or “deprecated” label, move it to an archive space and add a clear banner pointing to the current source of truth. Finally, use recurring reports or dashboards (e.g., pages by age, by owner, by space) so space admins regularly get a list of content to review, instead of relying on manual clean-up drives.

[Caity Belta]

Todd T. asked: We love using Templates. We also love using Live Docs. One of our challenges is that Templates can't exist as a Live Doc. Our workaround has been to create it, then convert it. Curious if there's a better workflow for this.

@Tiffany Scolnic answered: Templates today are page-based and you’ve basically found the “official” workaround, and there isn’t currently a native way to have a template that is itself a Live Doc.

[Caity Belta]

@Joshua Bertrand asked: One challenge everyone being a steward is a lack of consistency; how should i deal with that?

@Tiffany Scolnic answered: Give everyone stewardship, but don’t leave them to invent their own rules. We suggest you create a lightweight “Confluence hygiene” playbook with standard templates, page naming, labels, and a clear definition of when to update vs. archive. Make sure every key area has an accountable owner who can enforce those standards and handle edge cases. Then, bake in a simple governance rhythm, like quarterly reviews with a short report of stale pages so you can spot inconsistencies early and realign people without heavy process.

[Caity Belta]

Sindhu G asked: 1) Would love to understand how macros work
2) Is there a way to have confluence tables = gsheet rows/columns to make tables more effective & easy to use in Confluence

@Tiffany Scolnic answered: 

Macros: Suggest referring to the SAC guide

There isn’t a native “live sync” where Confluence tables automatically equal Google Sheet rows/columns, but you can get close in a few ways. The most common pattern is to embed the Google Sheet directly (using a Smart Link or the Google Drive macro), so people see and interact with the real sheet while keeping Confluence as the narrative/summary layer. If you need actual Confluence tables updated from Sheets, that usually requires a marketplace app or custom automation (e.g., using the Confluence and Google Sheets APIs) to periodically pull data in. A good hybrid is: use Sheets for structured data and calculations, surface key metrics or small summary tables in Confluence, and link back to the full sheet for deeper work.

[Caity Belta]

@Joshua Bertrand asked: How is an excerpt different from a smartlink then? Sounds similar?

@Tiffany Scolnicanswered: An excerpt and a Smart Link both help you reference other content, but they work differently.
Excerpt / Excerpt Include macros let you re-use a specific section of page content somewhere else. You mark the source content with Excerpt, then render just that snippet on another page with Excerpt Include so its great for “single source of truth” text that appears in multiple places.
Smart Links are primarily rich links to another object (Confluence page, Jira issue, Google Doc, etc.) that show title, status, and sometimes a small preview, but they don’t copy or sync a defined section of the body text the way Excerpt does.
So: use Excerpts when you want the same text block kept in sync across pages; use Smart Links when you want a contextual, clickable reference to something that lives elsewhere.

[Caity Belta]

@Jessica Hampton asked: Can the embedded JPD content of an Idea display in Confluence somehow like it can be embedded to display in a Jira work item Description when creating a Delivery work item?

@Tiffany Scolnic answered: Short answer: not in the same way.
Right now, JPD only supports embedding external app/content into an idea and embedding JPD views into Confluence, not pushing the rich “embedded” idea content into a Confluence page the way you can inject it into a Jira work item description. In Confluence, your options today are to 1) embed JPD views via Smart Links for a live, filterable view of ideas, or 2) link to individual ideas as Smart Links; there isn’t a native “embed this idea’s description/fields as live, synced content block” the way there is for Jira delivery tickets. If you need something closer, the current pattern is to use Smart Links or a JPD view in Confluence, or explore a custom/Marketplace app that pulls idea fields via the JPD API