How to Review a Projects Page Tree Confluence

There are 3 macros that let you to re-utilize content:

The Extract macro to ascertain a re-usable section, or 'extract', on a page – add content inside this macro, and y'all can reuse it on as many pages as you lot like.
The Extract Include macro (excerpt-include) to include the contents of an excerpt on another page.
The Include Folio macro (include) to include the unabridged content of a page on some other page.

For example, let's say you lot create release notes for each major release of your product, and you want to include the intro from each release notes page on a 'what's new' page. Place each release notes intro in anExcerpt macro, then add anExcerpt Include macro for each gear up of release notes to the what's new page. Your intros will magically appear on the what's new page, and if y'all update the release notes information technology'll automatically update the what'south new.

Excerpts: the intros to these pages are in excerpt macros.
Excerpt include: these are excerpt include macros.

Another example is one of the ways we use theInclude Page macro. Whenever the ellipsis ( ) appears in our documentation – for example, go to >Re-create – it's actually anInclude Page macro. We have a page with just that prototype on it, and so we can include information technology whenever nosotros demand an ellipsis.

Why exercise we do use anInclude Page macro for ane tiny image? Well, just in case that UI element is ever changed. If nosotros attach the paradigm to every page, there might be l pages we need to update when things change; if we use anInclude Page macro, we update one time and it's changed everywhere. Doing it this fashion too allows us to know how many pages nosotros're using the image on. By going to >Page Information, we can run into how many incoming links there are to this page, and that tells us how many pages utilize the prototype.

Create an inclusions library (optional)

Y'all can include content from any Confluence folio, simply y'all may want to create an 'inclusions library' to hold content that's specifically for re-use. The inclusions library isn't a specific feature of Confluence; the pages in the inclusions library are just like any other Confluence page. This is just atechnique you can use if yous desire a place to shop content that'south specifically for re-employ.

To create your inclusions library:

ChooseCreate and create a new page in your space
Enter a suitable title. We use '_ConfluenceInclusions' (the underscore before the title helps to let people know this page is special)
Enter some content andrelieve the folio
We enter text explaining the purpose of the inclusions library and how to re-use the content
Choose Space tools > Reorder pages and drag your new pageabove the space homepage
Go to your new inclusions page and chooseCreate to add together child pages containing your re-usable content

Because y'all've moved the pages to theroot of the space, they won't appear in the page tree in the sidebar. The pages volition be picked up by other searches though, as they're normal Confluence pages.

Inclusions library location: drag your inclusions library here, in a higher place the rest of your documentation.

Use folio templates

Creating i or more page templates tin can be a real time-saver if yous're creating a lot of pages with the same layout. If you're constantly calculation the same macros, like panels and table of contents, save yourself from RSI and put them into a template – you can start with one, but brand equally many equally you need to maximize your efficiency.

To create a page template that's available in all spaces:

Go to > General Configuration
SelectGlobal Templates and Blueprints from the list on the left
Cull theAdd global page template button at the top-right
Create your template page and chooseSalvage

For detailed info on folio templates, see Create a Template.

To get toGlobalTemplates and Blueprints , or any other admin folio quickly, striking/ on your keyboard and outset typing the proper name of the admin page you're looking for.

Draft your piece of work

When you lot're creating a new page in your documentation, yous'll likely desire to do information technology over fourth dimension, saving every bit yous go, and take a select few people review it to provide feedback. A loose description of this workflow is 'draft, review, publish'.

Yous don't desire any half-finished pages existence seen past your users, and about documentation needs to be reviewed before it's finalized, so hither'due south a technique for drafting pages and allowing for review:

Create a page and restrict its permissions
For example, y'all might restrict viewing to a group of people such as your team, or a few select individuals. On a public site, yous might restrict viewing to staff members, so that the general public can't see the folio.
Write your page content
Share the page with your reviewers and ask them for feedback (make sure you haven't restricted them from seeing the page!)
The reviewers can add together comments to the bottom of the folio or highlight text to add a comment inline. If you give them permission, they can besides edit the page content straight.
Publish the folio when set up, by doing the following:
1. Delete any comments on the folio
2. Remove page restrictions then that your audience can come across it

Yous've now published your page. The space permissions and site permissions now make up one's mind who tin see and/or update the page.

Utilise links and anchors

Add together links

In whatever documentation site, it'southward essential to be able to link from 1 page to another, and often to specific sections on a page. You tin can add any URL to a Confluence page and Confluence will automatically detect information technology and turn information technology into a link.

If you paste the URL for some other page in your Confluence site, Confluence volition display the link text every bit the folio proper noun and turn information technology into a relative link, meaning if the proper noun of the page changes, Confluence will adapt the link and so it doesn't break.

Add together and link to anchors

The anchor macro allows you to create anchors in your documentation, which can exist linked to from anywhere. I've added an ballast at the summit of this page then y'all can click to get back to the top.

To add together a macro and link to it from the aforementioned page:

Type{anchor in the editor, select the ballast macro and give your anchor a name (top in my example)
Select the text that'll link to the macro and strikingCtrl+Yard (Windows) orCmd+1000 (Mac) (this opens the link dialog)
ChooseAdvanced from the options on the left and type# followed by your anchor name (#top in my example)

Cheque out our documentation for links and anchors to get the full rundown on linking to anchors on other pages and other anchor goodness.

Useful macros

Confluence ships with a dandy range of macros, and there are a few that are especially useful in technical documentation. Here's a few:

Table of contents macro

The Table of Contents macro helps people navigate lengthy pages by summarizing the content structure and providing links to headings used on the page. The best office is, you don't need to practice anything except add together the macro; one time you've added information technology, it'll automatically notice headings and add them to the table of contents.

Tip, Note, Info, Warning, and Panel macros

Often when creating documentation, at that place are elements of a page that you lot want to highlight or draw the the viewers' attending to. Confluence ships with the Tip, Info, Alarm, Note and Panel macros, which will assist you focus a viewer'due south attending on a particular part of your content.

Tip of the day

Use the tip macro to give your readers handy hints!

Go along track of page updates

In Confluence, information technology's quite usual for a number of different people to update a single page. Technical writers need to know what happens to our documents, both during review and afterward publication.

Watch pages or the space

So that y'all know when changes are made, information technology's a good idea to watch pages or even the unabridged space. That style, when changes are made to pages you're watching, or someone comments on them, you'll get an e-mail notification letting you know who changed what.

Whenever y'all're on a page in your documentation space, choose theWatch button at the superlative-right of the page. From there, you tin choose to watch just that page, or all pages in the infinite.

View page history

Confluence creates a new version of the page every time someone edits the page. The page history shows all the versions, with date, author, and whatsoever comments made on the update.

To view folio history, get to the page and choose >Page History

On the page history view, you can:

View the content of a specific version of the page.
Revert to (restore) a specific version.
Select whatever two versions and enquire for a comparison, to run into what has changed between those two versions.

Take a look at Page History and Page Comparing Views for a detailed caption.

Prove a list of contributors

If yous want to see at a glance who'south updated a page or pages, you tin add together the contributors macro. This macro displays a customizable list of people who've contributed by creating, editing, or, optionally, commenting on the page.

Customize PDF export

If you're planning to provide a PDF version of your documentation – whether information technology be for email, download, print, or any other form of delivery – y'all tin customize the expect of the PDF by adding a title page, header, and footer.

The process you lot accept depends on whether you're trying to customize the PDF export for one space or for your whole site, so, if you're keen to make these changes, take a look at our page on Customize Exports to PDF for more than detailed instructions.

Confluence is already a swell tool for technical documentation, but you can still add to it depending on your documentation and workflow needs. Here are some useful apps available on the Atlassian Marketplace, about of which we use ourselves, which tin extend the functionality of Confluence.

New apps are hitting the market place all the time. This is by no means an exhaustive list!

Scroll Versions (supported by vendor)

Curl Versions, by K15t, allows you lot to tie versions of your documentation to versions of your production, so that when a new version of your product ships you can publish that version of your documentation. Create every bit many versions of your documentation as y'all like, make the changes you lot need to, and keep them up your sleeve until release time. Yous tin can even publish unlike variations of your documentation – like if you take versions of your documentation for different operating systems – to different spaces or Confluence instances.

Re-create Space (unsupported)

The Copy Space add-on, past Atlassian Labs, does what its proper noun suggests; it allows a infinite ambassador to re-create a infinite, including the pages within the space. Great for when you want a infinite template that you lot tin copy to create other spaces.

This app is also useful when yous demand to archive a copy of a electric current space at a particular point in time, like when you're moving from one version of your product to the next – re-create the infinite, give it a new proper name, and go on it wherever you like, all without losing the existing space.

At this bespeak this plugin won't copy page history, blog posts and e-mail.

Scroll PDF Exporter (supported by vendor)

If you're going to produce a PDF of your documentation space, wouldn't you similar it to be professionally formatted? The Scroll PDF Exporter, by K15t, lets you style single pages or whole spaces for export, using handy PDF templates.

Gliffy (supported by vendor)

Create diagrams, wireframes, flowcharts and more with Gliffy. Gliffy features a highly intuitive drag-and-drib interface, and allows you to export your diagrams in multiple formats, including: JPEG, PNG and SVG. Add Gliffy flowcharts, UI wireframes, and network diagrams directly to your Confluence pages to communicate your ideas visually, making them easy to empathise and faster to spread through your team.

Lucidchart (supported past vendor)

Lucidchart is bachelor in versions for Cloud and Server, and allows you to create and insert diagrams within your Confluence Deject environs. Quickly draw flowcharts, wireframes, UML diagrams, mind maps, and more inside our feature-rich editor.

The server version also comes with a free Visio viewer, so you tin can view Microsoft Visio (.vsd) files, Visio stencils (.vss) and it besides supports exporting dorsum to Visio.

Documentation theme (discontinued)

Confluence historically provided a theme specifically for documentation. This theme was removed inConfluence 6.0.

A number of the original Documentation theme features, such equally headers, footers and the power to add custom content to the sidebar, are available in Confluence'southward more modernistic default theme, which make it a dandy pick for your documentation space.