Welcome to the Skillbuilder: Using Confluence for Documentation and Knowledge

Bases.
This course is designed to expand your skills footprint on Confluence.
We’ll start with an overview of the content. Let’s look at what’s in
store for you….
In this training session we’ll be looking at how you can use the built-in
features of Confluence to generate a useful documentation platform.

We’ll look at how you can manage this content in Confluence, and we’ll
be looking at how to make documentation and Knowledge Base articles
easy to find.

When you have content that is easy to find and useful, there will be less
demand on the support team. They will have time to focus their work on
helping with more complex problems, freeing you to focus more time on
improving your products or workflows.
The training is designed for Confluence champions whose
maximum administrative access is at the space administration
level. It is for anyone with long-term exposure to Confluence as an
end user. The training is not just for Confluence Administrators.

A useful prerequisite would be the Confluence courses from

Atlassian University, but this training can be taken independently
of those courses.

Let’s look at those two sections in some more detail. First we’ll
look at building documentation. Throughout we’ll be looking at a
real life case study where we have tidied up documentation for a
product to improve navigability.
This training has two sections. In the first section, we’re going to
look at using existing functionality in Confluence to create
documentation.

In the second section we look at using Confluence as a Knowledge

Base, and the links in the product to Service Desk.
Each of these sections will relate to this real-life case-study.

We will show you some useful techniques to present content,

structure it, and use in-built Confluence functionality to surface
relevant documentation.
In the second section we’ll cover creating a Knowledge Base.

We’ll look at using templates and blueprints to standardize your

content.

We’ll also look at the linkage between Confluence and Service

Desk, which will help you to help your user-base find the content
they need .
First we’ll look at establishing a documentation space to support
your product, a kind of documentation 101. We will cover building
out content so that the people who use your products can find the
content they need easily and quickly.
In this section, we’ll look at creating a space and setting up a
navigation structure.
Confluence is often used for documentation; documentation for
products, for processes, for system set up and so on. However, if
you allow your content to grow organically and don’t plan for
growth or think about structure ahead of time, the content will
become difficult to use or retrieve and will of course becomes less
useful.

We’ll look at how we can best present and organize content in

Confluence so that it’s easy to find and use.

We’ll start by considering what a good documentation space is.

Let’s look at that now.
A good documentation space should be easy to use, people should
be able to find the content they need, and it should be easily found
through search.

The content should be well presented and use a consistent and

non-confusing design layout.

You should also make sure that the content fully meet the needs
of the end user, always keep the audience in mind. And of course it
must be well maintained. This means scrutinizing old pages for
relevance, updating old content, and ensuring pages are not scroll-
intensive, confusing or difficult to understand.
To create your documentation space, you should begin by thinking
about the purpose of the space.
Is the documentation for something technical? Or for an employee
handbook?

Consider the audience before you start.

And then think about the content, how are you going to manage
that? Do you need to create a new Space, or should you add a new
Space structure?

The answer is of course, it depends! And we’ll look into the

considerations here in this segment.

The content that goes into the space must be controlled and
managed, and you must take care with how it’s added. Plan to
avoid having a page hierarchy of more than four levels deep. Don’t
make consumers of your content have to dig to find content.

Also consider the things you need to do and plan for in order to
make your documentation easy to update and maintain.

We’ll look at all of these points in more detail in the next slides.
In Confluence, you should aim to avoid creating more Spaces than
necessary. If everyone has the permission to create a space, and
nothing is managed, the danger is that spaces will be created in a
very ad hoc manner, and a proliferation of spaces can result in
content being unmanaged.

Also, what happens often is that users will create a space that
covers content that is also covered in one or several other existing
spaces, causing a great deal of confusion. That said, it is often
necessary to create a new space. We’ll look at when it would make
sense to do so, and when it might make sense to use an existing
space.

If you’re creating an employee handbook, you’ll probably want to

include it in the relevant company space. There would be no need
to create a separate space with the same team accessing it, same
permissions, using the design and so on. But, if the documentation
is for a specific product, you’ll probably need to create a new space
to manage it.

If you want to limit access to a specific group of users, you might need a
new space.

You might also need a new space if the content is to be externally

accessible, to separate it from content that might be sensitive.

We’ll look a little into Spaces and space settings next.

First, let’s look at how to create spaces, and the permissions
needed for that.

In order to create a space, you’ll need the global permission.

Here, we see the global permissions that are accessed via

Confluence Administration. You’ll see that members of the
confluence-administrators group can create spaces, and in this
instance ALL members of the Confluence-users group can too. You
might want to constrain space creators to a more limited group of
users.
Take care when allowing people the ability to create spaces.

If you have a large Confluence instance, then if everyone can

create spaces in Confluence, it’s likely that content will get difficult
to manage. Without careful management, space content will be
replicated and people will not be sure if content should go into, for
example the Training space, the Training Team space, or the
Training Products space.
We also want to be careful of creating structures that are too
complex.

The general guideline is to keep pages no more than 4-5 layers

deep.

Content buried twenty levels deep will be difficult to find for end
users, while also making life difficult for those who are managing
the content.
Now let’s take a look at our first demo, covering the structuring of
content in an existing space.
Now we’ll look at another important consideration. Audience. It
will define your content.

Is the documentation for a technical audience, or is your space set

up as an employee guide?

In either case, you don’t want people to have to search for a long
time to find the answers they need; you want content that’s easy
to search, navigate, and then consume.

End user content will be different from content for that will be
useful for technical administrators. And of course if it’s technical
content, that’s going to be very different to content delivered for
people accessing an employee guide for the marketing team.

The ultimate goal of course is to make content easy to find and

use.
You can do that in a number of ways.

One way is by reducing the amount of content in a page. Less is definitely

more when it comes to content in a Knowledge Base. We’ll look at this in
the upcoming demonstration.

Another thing that you can do is move information in spaces up to the

first hierarchy level.

Let’s look at some examples to demonstrate this.

Here’s a great example of how you can improve your approach to
content and make your documentation easier to manage.

We have some Confluence documentation at version 4.2

Look at how much scrolling the consumer has to do. There’s a lot
of content here, and it’s presented in quite an overwhelming way —
take a look at the left menu. Today’s consumers do not want
reams of content to read through. In the more recent Confluence
content, there’s a real move to support people for whom TLDR (too
long didn’t read) is a challenge.

In the more recent content, that has changed….

Here is version 6.8

• As you can see, the new navigation has been reduced, it’s easy
to read through. You don’t see a lot of links that can be
distracting.
• Consumers can easily jump to useful page content from a right-
hand menu and also jump to other pages containing related
content.

We’ll look at managing pages and spaces in the next segment.

This segment was a documentation 101. We looked at some of the
basics around making documentation content easy to consume.
We’ve covered creating spaces or reusing spaces, setting up easy
to use navigation and the important considerations of audience
when presenting your content.
Next, we’ll look at some of the features of Confluence that support
you in building out and managing your content for documentation.
Confluence is the perfect place to create Documentation. There are
a number of features that help you with this.

In this segment we’ll focus on using the templating and blueprint

features of Confluence to help you present and structure your
content. We’ll look at setting up a space, and some of the
important considerations for when you set up a space.
Confluence has features that will help you to standardize content
and use pre-defined labels, and thus help you establish an ordered
Space that’s easy to use. Space settings help you control access
and permissions for content actions such as creation and deletion.
Confluence has documentation space blueprints, and page-level
blueprints for ‘how-to’ articles and troubleshooting articles.

And then of course there are templates that you can generate
yourself, which we covered in the Confluence content skill builder.

Let’s begin by creating a space and a page based on templates.

In the following demo, we’ll look at creating a space using the
Documentation Blueprint and using the how-to article and
Knowledge Base blueprints.
Space settings are important to understand when you’re setting
up your documentation space.

That’s what we’re going to look at in this segment.

We’ll look at the space key and space name, along with space
categories, space permissions and finally making a space publicly
accessible.
First, we’ll look at the Space Key.

A Space has a unique and immutable key. This means that you
can’t have a the same space key across a multiple spaces in one
instance. You can’t change the space key using out-of-the-box
Confluence functionality. The important thing to remember here is
to create a key that’s clear and easy to understand so that you can
avoid the difficulties entailed in trying to change it in the future.

If you look at the URL for content in a space, you’ll see that it
consists of the space key and the page name, so there’s no
problem in changing the space name, but you can’t change the
space key. So, make sure that you create space keys that don’t
need to be updated. Make sure that the space key isn’t, for
example, inadvertently offensive or inappropriate.
With space names, there are fewer restrictions.

If you do have to change the space name in the future, there are
some things to bear in mind. One thing is that your page links will
continue to work, even though now their address is somewhat
different. This might cause a little confusion, so whenever possible,
try to use a future-proof space name.
You can also give your space a space category using labels. Space
categories are useful because they create a taxonomy for Space
type. They allow you to group together similar sorts of content, like
documentation. This will help you to navigate to your space from
the Space catalogue in Confluence.

Categories are often used in third party apps and you can use
them in some Confluence macros to help surface content.

Next we’ll review space permissions.

First, let’s consider the different levels of permissions that are
available.

With global permissions for confluence, you’re able to set up who

can access Confluence, who has Administration access and who is
able to create a global space or a personal space.

Permissions are also applied at a page and at the space level.

At a page level you can restrict who can access or edit a page. Let’s
look at page level permissions first.
At the page-level, you can set restrictions on who can edit the
page and who can view the page.

You’ll know if page permissions have been added because a red

lock icon has been applied to the page.

Notice here that we have view level permissions added. This

particular restriction means that only Emma Rush, David Gee and
Robert Marshall can view the page, and nobody else. Robert
Marshall is only able to view the page, he is not able to edit it.

You should also be aware that page view permissions are

inherited by child pages.

In contrast, page edit permissions are not inherited. For

documentation, edit restrictions are very necessary so that only
designated editors of your documentation can update content,
rather than allowing editing by all of the Confluence users who can
access the space.

For both edit and view page permissions, you limit access to the content
to individual users, and groups of users.
It’s a good idea to add restrictions on content that is not yet
approved, to limit page access to the reviewers and approvers. For
example, you might add a new page of documentation which
needs to be reviewed and then approved before it’s made
available for general consumption. Add View or ‘View and Edit’
restrictions during this stage, then when the content is approved
you can remove the restrictions to make the content visible to all
of the people who have access to the space.
Space-level permissions are far more granular than global
permissions. They control the following:

The ability to:

• add content to the space

• edit all pages in the space
• delete any page in the space
• add comments to pages in the space
• administer the space
An efficient way of managing the space is to create two user
groups, In this case since the space name is documentation, we’ll
add documentation to the user group name that we will allow
access to the space. We’ll have two groups, documentation-users
and documentation-admin. We’ll add only those users who will
perform space administration to the documentation-admin group.

The Space Administrator can control access to the space by

selecting user-groups or users and allocating them permissions in
the space.

One thing to note is that space administration should be

constrained to a limited number of users, rather than many,
especially when the space is for documentation, which needs to be
managed very carefully.
Another important consideration is related to the delete
permission. You should consider granting this permission carefully,
because you don’t want people to be able to delete valuable
content and then have it lost. Of course it’s possible to retrieve
that content from space trash if you’re an administrator but
consider the administration overhead of having to retrieve deleted
content frequently. Also content might get completely removed
from the trash by purging it, and you would then have to sift
through confluence back ups to retrieve it.
It’s often the case that your documentation needs to be accessible
to the public who use your product.

Of course, you could insist that users sign up and get an account so
that they can access your documentation. This would be useful if
you need to manage access to your confluence instance carefully.
However, it’s often the case that you’ll have thousands of users of
your product and the cost of a large number licenses along with
the administrative overhead of managing all of those users might
be prohibitive. Let’s look at how it’s possible to allow access to
your Confluence instance without signing in.

First, let’s consider the impact of allowing public access into your
Confluence instance. Then we’ll look at how you can actually allow
public access via Confluence global administration and space
administration.
Security is a big concern when you’re allowing access to your
Confluence instance. If you decide that you’ll allow one or two
spaces to be accessed by users who are not signed in, then you
need to remember that accidents can happen, and maybe a less
experienced space administrator will accidentally give public
access to a space intended for internal use only. And what if there
was very confidential information in that space?

One way to get around this is to have your main Confluence

instance be available to all your employees, and then have another
Confluence instance that’s designated to allow non-signed in
users access. You can limit internal employees’ access to the
external facing instance to only those who need to administer
content in that instance. This approach does mean you’ll have
extra expense, and adds the second Confluence instance to your
company’s infrastructure. If you choose this setup, one way you
can save some administrative overhead is to use one of a number
of apps available on the Atlassian marketplace that will allow you
to easily publish a space from one Confluence instance to another.

We’ll look at how to set up a publicly accessible space in the next demo.
Finally, an observation. You might think that allowing commenting
on the content would be a good idea, but only allow this if you’re
managing your content very, very carefully, because people could
add comments that are unwelcome, argumentative or advertising
their own products or services.

So how can you communicate with your end users to make sure
that they’re getting the support they need, and that their valuable
feedback is being taken into consideration? You can provide a link
in the documentation to your support application. And what is the
ideal support application for Confluence? Jira Service Desk of
course! In the final segment we’ll show you how to do that.

So we’ve just looked at Space settings. We’ll do another demo,

then after that we’ll look at how you can improve user
consumption of content through page layout and use of macros.
In this demo, we’ll look at how to make your space publicly
accessible.
Let’s consider the ways in which we can improve usability of
content in confluence.

First, as we discussed in the previous segment, we should keep the

content layout consistent throughout.

Content should be separated using sections, so that users don’t

get faced with tons and tons of text. And if you do have a lot of
text on a page, you should definitely use the table of contents
macro and the anchor macro to jump to sections of text.

You should also consider using descriptive text, so instead of

linked text that reads, “read more”, you should add text that’s
descriptive, such as ‘for more information on available parameters
see the value reference guide’.

Let’s look at this in action.

In this demo we’ll focus on layout techniques for different types of
content.
Let’s quickly review the takeaways from the skillbuilder so far.

Use the built-in features of the application to help you produce

content that has a similar look-and-feel.

Use templates and blueprints for pages and also use space
templates

Use space settings to help you manage your content. When

creating a space, remember that you can change the space name
at a later stage, but not the space key.

Use permissions to carefully control who can access your content

It’s possible to allow public access to your content but do so only

after carefully considering the impacts.

Next, we’ll dive into using Confluence as a Knowledge Base along

with Jira Service Desk.
In this segment we’ll look at creating a Knowledge Base in
Confluence that can be used both by customers and your teams
from Service Desk.
Documentation should support your client base users. This is
where a Knowledge Base is invaluable.

Having a Knowledge Base can relieve the pressure on your support

team by allowing your customers and your team members to find
answers for their problems and issues themselves.

Any service requests can be automatically directed to a related

article in the documentation. The pattern of service requests can
identify gaps in your documentation or in the functionality of your
product, helping you identify user needs. Jira Service Desk links into
the Confluence documentation space to create an integrated
Knowledge Base and can be used responsively, to generate
Knowledge Base articles.

Before we move on any further, let’s first review exactly what Jira
Service Desk is and how it helps support your products, teams and
customers.
A Service Desk is a Jira Project with Support-related functionality
added in. The image you see in the slide is of a Jira Service Desk
project from the Jira view.

The people who work in this project and provide support are called
Agents. Agents, along with standard Jira users will get a standard
view of a Jira project with the extra Service Desk functionality,
such as support queues and customer lists.
The people who submit support requests are known as customers.
They see the Service Desk, or the customer portal, not the Jira
Project. They access this via a separate URL. They do not see the
Jira interface or Jira functionality. They see a user-friendly portal,
such as the one you see in the slide, where they can submit a
request, which is a simplified version of a Jira issue.

The customer has the extra benefit of being able to manage their
request using email.

What Jira Service Desk does and what is important for us, in this
course, is that it can link a Service Desk project to an integrated
Knowledge Base.
There are two types of user for whom this integration is invaluable,
and we’ve already mentioned these two user types in the previous
slides. They are:

The customer using ServiceDesk and User Agents who take care of
customers.

Let’s consider how a ServiceDesk works. It allows for customers to

request support via an easy-to-use portal. Then:

As a customer:
You type in your service request and you will automatically be
directed to related articles. This will help save you time because
the answers are at your fingertips. If the answers are not there,
you can create a request.

As a User Agent:
The answers are available to you too, via the Knowledge Base, and
you don't have to waste time repeatedly sending information to
customers.

So how do we set this up?

Let's see in the next demo….
In this demo, you’ll see how to link to a Knowledge Base Space in
Confluence from a Service Desk.
Let’s review the access permissions for this linked Knowledge Base
space.

Service Desk agents need to be able to access and manage

content in the linked Knowledge Base space. They need to be
granted space permissions so that they can view add and
potentially delete content. They will need to use a Confluence
license in order to do this. Their access permissions can be
controlled via space administration.

You might be concerned that allowing access to your Knowledge

Base will use up Confluence licenses. You don’t have to give
customers a Confluence license to access content in the
Knowledge Base.

We’ll consider the permissions settings for Customers in the next

slide.
In the Knowledge Base administration area of your Confluence
instance you can manage who accesses the Knowledge Base
content in the Access area.

You can select either “All active users and all customers” or “Only
licensed users who have access to the space”.

The first option “All active users and all customers” means that
everyone with access to your Service Desk will be able to access
content in the linked Confluence space. These people get very
limited Confluence access.
Unlicensed users can:
• View pages via the Jira Service Desk customer portal.
• Follow a URL to a page and then navigate within the linked
space.

The second option obviously requires that users have a Confluence

license to read Knowledge Base articles via the help center or a
link that your team shares. This option is best if only your team or
organization needs to read and write articles.
Now let’s see another demo.
In this demo we’re going to allow unlicensed users to be able to
access the content in the linked Knowledge Base.
Next we’ll look at who can manage and change the users who
access Service Desks.

We’ll look at the different types of users in more detail, but first
let’s cover the different permissions needed to manage different
users:

Jira administrators create Service Desks, manage licenses and

users across multiple projects.

Jira project administrators can add agents. They can also manage
customers and organizations. We will talk about what this means
in a moment.

Agents can manage customers and organizations.

Let’s look in a little further detail at the different users for the
Service Desk ….
Managing who can use your Knowledge Base and their
permissions is essential in creating a Service Desk that contributes
to the Knowledge Base.

In the Service Desk, the main user set by by your Jira administrator
will be the Project administrator. The Project administrator can
manage the other users’ permissions, such as who can see the
project's issues, and create, edit and assign them.
Agents work on customer requests and add customers to the
project. When a new agent is added into the project, the agent is
also assigned a Jira Service Desk license and added to the service-
desk-users group.

Customers are the main group of users who send requests to your
Service Desk.
Organizations are groups of customers that can be used in
multiple projects. When you add an organization to a project, its
members can raise requests in the project and share them with
the organization.

They're also notified about the organization's requests, and can

view and search them on the My Requests page in the portal.

By default, you need the Service Desk Team role for a project to
manage organizations in it. However, a Jira administrator can
restrict organization management to Jira administrators by turning
off the Organization management setting for that project.

To choose who can view the portal, who can send requests to the
Service Desk, and who customers can share requests with in your
Service Desk project, select Settings, then Customer permissions.
Let’s review what we’ve covered so far.

Service Desk provide self-service support through the connection

to Confluence spaces which are used as Knowledge Bases.

We looked at the different types of users who operate in a Service

Desk: the Jira administrator, the Project administrator, Agents,
Customers and Organizations.

Knowledge Bases can be created easily and quickly, and blueprints

and templates can help to present and structure this content.

Next, we’ll look at how you can create pages from Jira issues.
Having linked a Confluence space to your Jira Service Desk project
as a Knowledge Base, agents are now able to create Knowledge
Base articles from your Jira tasks.

From a Jira task, you can create:

• a Knowledge Base article,
• a ‘how to’ article,
• or troubleshooting steps

using a blueprint.

You can also link to an existing Knowledge Base article in the

linked Knowledge-base space.

Let’s look at this in a demonstration.

In this demo we’ll see how to create content in Confluence from Jira
Service Desk.
The configuration of your Jira Service Desk allows you to map
labels to your request type.

This feature can be used to ensure that only appropriate pages are
recommended to a user after they choose a request type.

Let’s see how this is done in a demo.

In this demo we’ll look at using labels to map Service Desk
requests to Knowledge Base pages.
That demo concludes this segment.

What are our main takeaways?

We looked at how you can create a linked Knowledge Base in

Confluence from Service Desk to help customers by providing a
self-service support solution. Customers don’t need a Confluence
license in order to access the content in the Knowledge Base
space.

We also looked at how you can manage content using labels, and
how as an Agent you can create content in the Knowledge Base
from Jira.
That brings us to the end of the course — now it’s time for you to
try things out for yourself in the homework exercise.

In the homework, you’ll create a Knowledge Base space in

Confluence from Jira Service Desk, and then allow customers to
access the space without granting them additional Confluence
licenses. You’ll also create a page in the Knowledge Base space
from a Jira issue.
We hope you enjoyed this Skillbuilder training and learned useful
things that will help you in your daily job as Confluence
administrator.

Fur further information, visit our online resources including

Atlassian University, Atlassian Community and Atlassian's
product documentation.

For more in-depth help, contact Atlassian Support or locate one

of the Atlassian Solution Partners near you.
Congratulations on completing this Using Confluence for
Documentation and Knowledge Bases course!