The Detail Department

You are here: Home / Archives for confluence

We need to talk about Documentation

by

Last week, myself and Kelsey van Haaster presented a talk at the Agile Business Analysts Meetup in Melbourne. The Agile BA’s meetup is my favourite Melbourne meetup group (it ranks second only to the Sydney Business Technology User Group that I used to help run in Sydney).

The talk was in two parts – Kelsey talking about Requirements documentation and me talking about Help documentation. The theme of our talk was using Confluence as a tool to help make documentation more a part of the agile software development process, rather than an afterthought or a tedious chore.

Having all the documentation in one place that everyone in the team is responsible to update, is, in my opinion, the only way to do documentation.

Read more about Documentation

Tools to help write help documents

by

If you are going to be writing help documentation, having some good tools will help make the process a bit easier. Here is a list of tools that I have used or would like to try.

Writing Help Documents

  • Screensteps or Clarify-it
    • (they are from the same company, and I really can’t see what the difference is, however Clarify-it comes with a skitch-like tool for sharing screen shots).
    • Really helps you to think about the problem in a step by step way.
    • Desktop and Network versions are Cheap. Just get it!
    • Inbuilt screen shot and markup tools.
    • There is an online version (Screensteps Live) to host your help pages, but it is expensive. Just export the HTML to your preferred help system.

Read more about Help Systems

Fragmentation of Task Functionality in Confluence

by

I am trying to work out the best strategy for my clients to use for doing lightweight task management in Confluence. I thought that since we have the new Task features and Workbox in 4.3 that this would be a no-brainer. We would not need Ad hoc Workflows, we can just use the new functionality.

Confluence has released what looks like a great new feature in Confluence 4.3 – the ability to have Tasks on the page, and a centralised notification box called the Workbox.

With a number of new Confluence features lately, I feel that the release of this new feature is a bit half-baked and it doesn’t actually do all the things you need it to do. (I think it’s because I love the product, I hold it up to such high standards, and expect things to work really well first up).

[Read more…]

Using Graphviz in Confluence – A Tutorial

by

I have always liked to do flowcharts. Simple flowcharts are good flowcharts – a picture tells a thousand words. I also love Confluence, and love the hierarchical nature of the structure of Confluence – much like a flowchart. Now we combine the two and we have a great way to communicate information. Enter Graphviz and the Graphviz Confluence Plugin.

This is a Tutorial to get you started with using Graphviz in Confluence to produce flowcharts quickly and easily.

[Read more…]

Excel, Charts and SQL in Confluence

by

One of the disadvantages of Confluence is how difficult it is to use Tables, especially when they get large. One of the options is to keep tabular data in Excel and display the contents in Confluence. Or better still, get the data direct from a SQL Server to display in Confluence then show that data as a Chart.

Confluence 4 seems to be a bit better at handling tables, but Excel is still the king for displaying and working with Tabular data.

Some resources to help with showing Table data are: [Read more…]

Confluence is not a Word Document

by

You’ve just installed a shiny new Confluence set-up for your organisation, now where do you start with writing content for it? Here are my thoughts on writing for Confluence and a few tips and links to help get you started.

My two main points for writing content for Confluence are:

  • Confluence is not a Word document, and
  • Confluence is not a file share.

Continue reading about Confluence not being a Word Document…

Creating Word Documents from Confluence

by

Expanding on from my One thing in One Place,  Once post on reusing Confluence content, the next step is to export that content from Confluence into Word and or PDF to produce printable manuals from your content. Yes, I know, I have that thought too, why would you need to print something when it’s on Confluence and readable on the screen and directly linkable to the content. Well, sometimes I just have to lose that battle and understand that people do in fact like to have a paper copy of documents to read. So the important thing here is to ensure that the Word document or PDF content comes directly from your Confluence content so that you minimise the versioning issues. If you do a major update to your Confluence content, it’s a relatively straightforward matter of exporting and releasing a new version of your Word or PDF document.

To export from Confluence to Word I use Scroll Office from K15t. I have tried the Scroll Wiki exporter to export directly to PDF but it was an early version and I had some issues with it, and I prefer to tweak the export in Word first before doing the PDF output so I will focus on Scroll Office here. (There is also the Confluence PDF Export option if you want to play around with customising it to work for you). Scroll Office is a great product. There are some tricks to getting it working well, and there is still a little bit of tweaking required in the final Word document, but overall it is great – have a look at the documentationto get started with using it. And I must say that the guys from k15t have been very helpful in getting a few bug fixes done whilst I’ve been setting up this export process.My Confluence instance is a help system for a software product. The pages in Confluence are structured in a particular way:

  • Each screen in the software has a page in Confluence (this helps if we want to add som screen level context specific links to the app at a later date).
  • The hierarchy of pages in Confluence is set up exactly the same way as the menu structure in the software, that way people can navigate to the page that describes the screen they need some help about.
  • Each page describes what the screen does and also has a Navigation section that tells the user how would they get to this screen in the software. This is useful if they have come to this page via the search or via a hyperlink.
  • Each page also has links to the next most relevant topic, or the next screen that the user would use if they were on that screen.
When preparing the Word manual for the software there are a few differences with the way the content needs to be structured. As the document is in a linear form, and most users will be seeing the manual in their training course, we don’t really need all the navigation instructions or the links to the next topic, as the next topic is right below it on the page. There may also be some text that is specifically in the manuals such as training exercises or introductory comments. So there is a little bit of tweaking required in Confluence to be able to produce the ideal Word export.The first thing to understand when using Scroll Office is how Scroll Office handles headings – that will help you work out the way that the content for export should be structured. Basically the heading levels that have been used in Confluence are ignored and it all works on a hierarchy. Page Names are Headings in Word, then the h1. to h3. etc become headings under that heading. Pages in the hierarchy under that page also become headings, so depending on your hierarchy of your pages in Confluence you could have a very nested heading structure in Word. This is not ideal. So the trick (for me) is to create new pages in Confluence that will be my pages to export. I then include the content from my regular Confleunce pages into these pages and set up these export pages to have a much flatter hierarchy and heading structure (eg by including multiple pages into the one).

As mentioned above, I also want to exclude some of the content from my main pages in the export, so this is where the wonderful {builder-show} macro comes into it’s own. In the Base Page (the page where the content is edited), I wrap different content sections in the builder-show macro to show only certain parts of the page in the Base Page or the Manual Page. In the Manual page I use the {import}Macro to import the contents from the Base Page. See the example content below.

Page Setup in Confluence

Page Setup in Confluence for Word Export

This way I have two pages of content but only one page that I need to maintain. The next step is to import two or more pages into my manual page, separated by headings. It does not matter that these manual pages are quite long, because I hide them from the main navigation menu – the users who come via the navigation only see the Base Page.

Another trick I use is the {scroll-pagetitle} macro. I want the headings on the Word document to be the same as the headings on my Confluence content, but as I’m creating new pages to export the content, I can’t have the same page names in Confluence. So I just add the word Manual to the end of my page name for my manual pages and then use the pagetitle macro to revert back to the same title on the Word export.

Word Tweaks

Of course the best export from Confluence only happens if the Word Template is set up well with good heading styles (down to about heading level 6), bullets, numbering, headers, footers, page numbers, title pages etc. Spend some time tweaking your Word Template along with your export pages in Confluence to get the best results. There are some tweaks I do in Word, for which I use Macros (these are for things that are specific to my Confluence instance so I won’t bore you with the details). It is great that Scroll Office allows the document template to be a macro enabled template, so the macros are already built into the document when the document is exported.I do suggest that you do a thorough check over your Word document once it has been exported and tweak the content looking out for the following:

  • Update the Table of Contents.
  • Remove additional paragraph returns after images (k15t said they plan to fix this in an upcoming release).
  • Adjust page breaks.
  • Check spelling again (yes, it is amazing how many spelling errors you pick up seeing it in a different format).
  • Resize images or adjust formatting if it helps to get things to fit on the pages better.

The less you need to do with final tweaking in Word the easier it is to re-export the content next time.

The final step is to save the Word document as a PDF file, which of course Word 2010 does out of the box. After you have created this PDF file it may even be worthwhile adding these documents to a page in your Confluence site so that users can download the completed PDF file.

Using these steps I have been able to create 3, 150 page word manuals and a few smaller quick guides on how to use the software – all based on the base content pages.

I hope this helps you, but if you have any tips or other suggestions on how to get great looking printed manuals from your Confluence content then please let me know in the comments.

Building a Glossary in Confluence

by

When building a Confluence site, or any Help documentation, it is very important to have a Glossary to help explain some of the terms that will be used in the documentation.

Confluence has a few examples of glossaries in their own help system, but of course I wanted to take it a step further – I wanted my glossary terms to have hover text in the main body of the help system, then with a hyperlink to the full glossary text. Also, the glossary should be on one Glossary page and be able to be included in the printed documents.

So, of course, it’s User Macros to the rescue – that along with a lot of help from the Confluence support forum, here’s what I came up with:

The Glossary Macro

{anchor:$ParamName}
h3. $ParamPhrase
{cloak:id=$ParamName}
{multi-excerpt:name=$ParamName}{html}<a style="text-decoration:none; border-bottom:2px dotted; border-bottom-color:#008000" title="$ParamTooltip" href="Glossary#Glossary-$ParamName">$ParamPhrase</a>{html}{multi-excerpt}
{cloak}
$Body

Create the macro to “Convert wiki markup to HTML”.

Breaking down the macro:

  • We create an anchor to come back to this Glossary entry at any time from the main content.
  • The Parameter phrase is shown in a heading 3 style. The phrase can contain multiple words – eg “Glossary Entry” may be a phrase for a Glossary term.
  • There is a cloaked (hidden) section containing a multi-excerpt macro, which contains some HTML formatted text. The multi-excerpt macro will be used to display the Glossary term in our main content pages.
  • The HTML text has a dotted green underline and a hyperlink back to this page, it also has a “title”, which forms the hover text (or Tool Tip) of the Glossary term.
  • Finally the body of the macro is shown – this is the full text of the Glossary.

Glossary Macro Usage

We call the Glossary Macro on our Glossary Page with the following code entered into the Wiki Markup of the page.
{glossary:Name=MyName|Phrase=My Glossary Phrase|Tooltip=My Hover or Tool Tip Text}The main description of the Glossary term. 
This can contain as much information as needed.{glossary}
You end up writing the ToolTip again in the the body, but as both bits of content are stored in the same place, it is easy to update them.
This will display on the page as:

My Glossary Phrase

The main description of the Glossary term.

This can contain as much information as needed.

The rest of the content is hidden because it is inside the cloak macro.

The GL Macro

This is the macro that allows us to use the Glossary term in the main content of the Confluence site and link back to the Glossary page, as well as show the ToolTip on hover over the link.
The macro text is simply to use the multi-excerpt include macro to show the multi-excerpt text we set up on the Glossary page.
{multi-excerpt-include:pageTitle=Glossary|name=$paramName|nopanel=true}
This will display our Glossary phrase as such:
This is My Glossary Phrase used in a sentence.
  • When you hover over My Glossary Phrase the text “Hover or Tool Tip Text” will be shown
  • When you click on the phrase it takes you straight to that anchor on the Glossary page.

GL Macro Usage

The GL macro is simply called by entering the following text in Wiki Markup mode.

This is {gl:MyName} Phrase used in a sentence.

(macro names are always lower case).

Overall Glossary Page

See the content on the Confluence documentation that I wrote about creating a great looking Confluence Glossary page with an alphabetic index at the top of the page.

So it’s very simple to include Glossary words in the body of your Confluence document, the overall Glossary page looks good, and all of the glossary content is maintained and updated in One Place, Once.

I would love to see if you have any ideas for any improvements in this user macro, or if you have a great Confluence glossary page to show off.

The “One Thing, in One Place, Once” Rule using Confluence

by

As a database designer, I am a huge believer in the “One Thing, in One Place, Once” rule (aka Normalization, in database speak).

As I’m currently building a full enterprise help system in Confluence, of course I’m going to extend that rule to my help content also.

I started with the ideas of Re-Using Content in Confluence and Building an Inclusions Library as written by Sarah Maddox from Atlassian, then as I started to need more features, I moved on to some of the other methods for content re-use, so I thought I would summarise them.

There are 4 ways that I use to re-use Content. The {include} macro, {excerpt} macro, the {multi-excerpt} macro and the {builder-show} macro. The {include} macro is the simplest and the {builder-show} is the most complex and most powerful.

I’m mainly using these features to produce a printable version of the help content, which is a bit different than the Wiki content, as it is presented in a linear fashion, and doesn’t have as many links to content unrelated to the narrative of the document.

Have a look at the following diagram, it shows some examples of the 4 macros that I regularly use. The first box is the base page, where the content is originally created. The second box is the wiki markup mode of the page where the content is included. The third box is what will show in the final layout of the page.

(click to enlarge)

Include Macro

The {include} macro simply includes the full content of the base page into the display page.

I use this macro for small notes and info panels that are used in multiple places.

On the display page enter the following in wiki markup mode:

{include:Base Page}

The {include} Macro is a bit limiting as most of my main pages has a section at the top that shows how you navigate to this screen – I don’t need that in my printed document.

The {include} Macro can be used from other spaces with the following syntax {include:SPACEKEY:Page name}. (Also see the Perimeter Plugin from CustomWare for the {secure-include} macro, which is useful for including from spaces that the user does not have access to).

Excerpt Macro

The {excerpt} macro allows for a defined section of the base page to be included in the display page. The content that is between the two {excerpt} tags can be included in the display page.

On the display page enter the following in wiki markup mode:

{excerpt-include:Base Page|nopanel=true}

I use this macro only occasionally for very simple pages as I find it a bit limiting as it can only be used for one continuous section of content.

The {excerpt-include} macro can only be used for content within the same space, similar to the {include} macro.

Multi Excerpt Macro

The {multi-excerpt} macro is part of the Multi-Excerpt Plugin. This is a very cool plugin, but it does cost – luckily it’s not that expensive.

This plugin allows you to have multiple excerpt sections in the base page appear in the display page – the cool thing is that the excerpts can be displayed in any order you want.

Each excerpt defined must have a unique name on the page.

On the display page enter the following in wiki markup mode:

{multi-excerpt-include:pageTitle=Base Page|name=excerpt1|nopanel=true}

The addition of the spacekey parameter allows the Multi-Excerpt macro to be used across spaces, so it is quite useful.

I use this quite a bit, but it still has one limitation – you can’t nest multi-excerpt macros – but I may be asking for a bit much there.

I use it to include the overall page description, then the screen shot, then the steps on how to use the screen, but exclude the navigation and the links to other pages, in my printed content.

Builder-Show Macro

The {builder-show} macro is part of the Adaptavist Theme Builder Plugin and is the coolest macro. The way I use it basically turns Confluence into a bit of database – yes it’s a bit complex to set up, but once it’s set up, the maintenance of the pages is going to be very easy.

Here’s how I use it – There are a number of fields on each screen. The same field can be used in multiple screens, and the same description is applicable to each screen. If I keep the description in one page, then I can use that description in multiple pages – but it only ever needs to be updated in the once place in future.

With the same field description being used on a few screen pages, and the printed manual for those screen pages, it can be used in up to 5 places – all based on the same source.

The main set-up for this macro is done on the base page, where we put in codes to say which pages the content will display on.

{builder-show:title=Display Page}
This is the first excerpt from my page
{builder-show}
{builder-show:title=Base Page}
This is the rest of my page
{builder-show}
{builder-show:title=Base Page, Display Page}
This is the second excerpt from my page
{builder-show}

The first and third sentences will be shown on the display page, and the second and third sentences will be shown on the base page. Sentence 3 will be show on both pages.

The display page contains the one macro – the {import} macro.

{import:Base Page}

And that’s all there is to it :).

There is one small limitation with this macro – the content on the display page must be shown in the same order as it is on the base page.

I hope that has helped give you some ideas on how to re-use content in your Confluence site, and if you have any more cool macros to share, please leave a comment.

Getting into my Confluence Editing Groove

by

I love Confluence. If I could use Textile Markup to do any editing of documents at any time, I would. If Textile Markup was in Google Docs, I would love it (although, now that the keyboard shortcuts are more similar to Word, it’s a little easier).

Of course Confluence is more than about the editing, but in this post I’m going to be concentrating on the editing features of Confluence – especially Wiki Markup. I do not use anything other than Wiki Markup when editing in Confluence*. Even though the Rich Text Editor has improved in later releases, it is still much easier to do “* type the text” to create a bulleted list than to take your hands away from the keyboard and find the icon to apply the bullet style.

(* I do use Rich Text editor when working with large tables – that is my only concession).

I am currently writing a very large help system in Confluence for a web based App that I work with. There is so much to do, that I need to be quick and have systems in place to do things without repetition.

The one thing that is difficult about editing in Confluence as much as I do, is that it is slow – this is the nature of web based applications It is slow to get into edit mode, and even slower to save the page and display the finished content again. There is Word connectors and WebDav, but they can be a bit of a pain and I just want to quickly edit text in a simple text editor. I can guarantee it that every time you think that a Confluence page is finished – there is always one tiny edit that needs to be done, one comma missing or a spelling error – it is this continuous editing that takes so much time.

What I also want most of all is syntax highlighting in Wiki Markup mode – so I can concentrate on the text, and ignore the macro’s and links etc, or quickly find that h2. line with the bit of text I need to edit.

The Confluence Plugin “Confluence In Place Editor” (CIPE) is great as it allows you to edit just the section of the page that is within a heading, and the main advantage of it, is that a text popup window pops up instantly – no more waiting to launch into edit mode.

So I have come up with my workflow for editing Confluence pages – using a number of tools, and I think, even though it is a bit clunky it is faster and cool, because I now have syntax highlighting.

My Apps

These are the apps that I have open when writing my Help System
  • My app in the browser depending on which one I’m writing about (generally Firefox).
  • Confluence in Firefox (with Text Area Cache plugin enabled – this is a godsend – just do not use any Web based editing eg Confluence, WordPress etc without it).
  • Notepad ++ (yes, I’m a Windows user, you could do similar with TextMate for Mac).
  • Snagit (yes, Snagit is now available for Mac also).
  • Dropbox (definitely the best thing since sliced bread).
  • The Confluence In Place Editor Plugin

Notepad++

I Created a User Defined Language for Confluence – based on this site and refining it myself.  Text I have formatted in different colours are:

  • ! for images
  • * for bold and bullets
  • # for numbered lists
  • Numbers
  • {text between braces} for macros
  • h1. h2. h3. etc
  • [Links to Pages] in blue

I’m sure there are more things I could colour, but that is  a good start and makes the Wiki Markup much more readable.

When editing your document, save the file in dropbox so it’s updated constantly and backed up (just as it would be if you were editing in Confluence).

Snagit

All screen shots of my App are done in Snagit. I don’t upload them to Confluence until the very end as there is always one last minute change you want to do. I put numbering on the screen shot to point my help text at the correct location on the screen – I just use the default Snagit numbers.
It is very helpful to have the text file and Snagit side by side so you ensure that the numbering in the text is the same as the screen shot. (Win Key + Left and Right arrows FTW!)
I also upload my .snag files and my .png files to Confluence, so I don’t have to store them in a separate location – Confluence is my master repository for images. When I need to edit my screen shots for a new release, I just download the .snag file, modify it, create the .png file again, and upload both files back to Confluence.
I use the idea of the _includes page as an image library as shown in this post.

My Workflow

Here is my workflow for creating and editing my Confluence pages:

  • Create the screen shots and work out what needs to be written about.
  • Add any numbering or other enhancements to the screen shot in Snagit.
  • Create the text in Notepad++, viewing the Snagit screenshot side by side with the text to get the text right.
  • Add the Screen shot link into the document based on the name you have called it in Snagit and the name of your Image Library page.
  • When the text looks right, paste it into Confluence and have a look at the layout and structure of the document. (Note, there will be no screen shots visible yet – this makes it a bit cleaner to focus on just the words).
  • Display the Confluence page and the Notepad++ document side by side on the screen, so as you see things in the Confluence page that need fixing, you can quickly edit the Notepad++ document. (You can do this with two browser windows open side by side also and use the normal Confluence editor).
  • Check the spelling in Confluence as it uses your built-in browser spell checker with the words underlinked (Notepad++ spelling checker is not that great).
  • Paste the edited text back in to Confluence when you are done. Using the CIPE plugin helps with that as it makes it much quicker to load than going into edit mode.
  • Once all the text is correct, drag and drop your image files to the Image Library page.
  • Refresh and check the completed page in Confluence to make sure everything looks great.

So, that’s my workflow. What is yours? Do you have any great ideas that will help streamline my processes, or will my ideas help streamline your processes? Let me know in the comments.