How to Create A Specific User Guide in Confluence

Hi! I would like to incorporate my user guide into Confluence, so we can share this with our users. I would like to build this in confluence rather than just upload my user guide, as I know I will be making revisions going forward.

Has anyone built their specific user guide in Confluence? Thoughts and tips on how I might design mine? Thank you!

3 comments

Susan Ostreicher Community Champion Jun 26, 2017

Hi Barbara, 

Not sure if it will be relevant, but I'm currently translating several user guides for software used inside our company from Powerpoint to Confluence, and I'm happy to share what's worked so far.

To get a better sense of what you're working on, what is your user guide about? Who is it for, and when do they use it?  What format is it in now?  

Will it exist in a Confluence space along with other content?  If so, what other kinds of content will be there?  Is all the content for the same audience?

 

Hi Barbara,

We use Confluence to author the user documentation for our product SMARTset at 4NG.

We have a space for each manual and an extra space where we store all our shared excerpts (we use the Multiexcerpt Macros plugin).

The Confluence content is also the context sensitive help and we achieve that by adding in 'special' tags into the Confluence content that we want to be linked to a web location in SMARTset. Each space is exported to a single, static HTML package (all the pages, images and CSS) as part of the build process using the Confluence API.  The document builder also creates a full PDF of the each manual.

This all sounds like a shed load of work and you would be right!  

The Confluence API isn't that easy to follow, the extracted HTML needs a LOT of cleanup and the page hierarchy is very difficult to replicate.
We end up with something pretty decent and coupled with the context sensitive aspect, it fits our needs but it is far from perfect.

If I were doing it all over again, I would probably not use Confluence at all, it's just too limitiing and cumbersome. I'm sure there are better documentation tools out there that produce first class manuals and online docs and have a decent, structured search mechansim. In fact that's one of our biggest issues, finding stuff in Confluence.

If you intend to just provide users anonymous access to your Confluence site then a lot of these issues won't be a problem for you I guess.  This is certainly the Atlassian approach so they have a vested interest in improving the tool.

Hope that helps,

Steve

Hi Steve.

Thanks for sharing.

My experience is that confluence (cloud) has its strengths elsewhere than exposing documentation in a public domain, as where internet users can access how-to-documents or other knowledge-base documents.

When receiving a document, the user is not only presented of the content of the document, but all the visual aids, that goes with confluence, such as navigation etc. Menus are rendered for users to interact, as if they were maintaining the documentation. I am aware of other solutions, including custom coding and accessing the content over API, where you get an highly customized experience, which is the point - not all want to go down that road.

We are kind of missing the ability to expose the content through a simple and customized portal - Equivalent to JIRA exposed to the support product at Atlassian.

For now, we have moved forward with Intercom (intercom.io), where the ability to expose documentation focuses on the document/content, and not all the visual clutter - it is a really calm down-toned user experience.

 

Cheers!
Theodor.

We have built our User Guide for ParkMyCloud in Confluence. We have had a lot of positive feedback from our customers on the ease of finding what they need through the search feature. You can find the guide here.

Comment

Log in or Join to comment
Community showcase
Bridget Sauer
Published Jan 29, 2018 in Confluence

Showcase: How LinkedIn does Content Lifecycle Management (12 Steps)

LinkedIn, the world's largest business network has an exceptionally large Confluence instance. In their case, large means millions of pages and thousands of spaces. In this Showcase, we're focusing i...

921 views 0 12
Read article

Atlassian User Groups

Connect with like-minded Atlassian users at free events near you!

Find a group

Connect with like-minded Atlassian users at free events near you!

Find my local user group

Unfortunately there are no AUG chapters near you at the moment.

Start an AUG

You're one step closer to meeting fellow Atlassian users at your local meet up. Learn more about AUGs

Groups near you
Atlassian Team Tour

Join us on the Team Tour

We're bringing product updates and pro tips on teamwork to ten cities around the world.

Save your spot