A few months ago, I asked my publisher to take my Confluence wiki book out of print. The book is titled “Confluence, Tech Comm, Chocolate: A wiki as platform extraordinaire for technical communication”. It takes a while for the going-out-of-print process to ripple across all the sources of the book, but by now it seems to have taken effect in most sellers.
Why did we decide to take the book out of print? I’m concerned that it no longer gives the best advice on how to use Confluence for technical documentation. The book appeared early in 2012, and applies to Confluence versions 3.5 to 4.1. While much of the content is still applicable, particularly in broad outline, it’s not up to date with the latest Confluence – now at version 5.6 and still moving fast. I thought about producing an updated edition of the book. But because I don’t use Confluence at the moment, I can’t craft creative solutions for using the wiki for technical documentation.
Here are some sources of information, for people who’re looking for advice on using Confluence for technical communication:
- If you have a specific question, try posting it on Atlassian Answers, a community forum where plenty of knowledgeable folks hang out.
- Some of the Atlassian Experts specialise in using Confluence for technical documentation. The Experts are partner companies who offer services and consultation on the Atlassian products. The company I’ve worked with most closely on the documentation side, is K15t Software. I heartily recommend them for advice and for the add-ons they produce. For example, Scroll Versions adds sophisticated version control to a wiki-based documentation set.
- AppFusions is another excellent company that provides Confluence add-ons of interest to technical communicators. For example, if you need to supply internationalised versions of your documentation, take a look at the AppFusions Translations Hub which integrates Confluence with the Lingotek TMS platform.
A big and affectionate thank you to Richard Hamilton at XML Press, the publisher of the book. It’s been a privilege working with him, and a pleasure getting to know him in person.
For more details about the book that was, see the page about my books. If you have any questions, please do add a comment to this post and I’ll answer to the best of my knowledge or point you to another source of information.
This week I’m attending STC Summit 2014, the annual conference of the Society for Technical Communication. Where feasible, I’ll take notes from the sessions I attend, and share them on this blog. All credit goes to the presenters, and any mistakes are mine.
The Language of Content Strategy is a book by Scott Abel and Rahel Anne Bailie. In this session at STC Summit 2014, Scott Abel discussed the content strategy, tools and technologies behind the making of the book.
Time, money, skills and experience are in short supply. Hand-crafting content is expensive, time consuming and not scalable.
The demands of the audience are changing. People use social media, rather than going to a specific website to gather information.
To meet the demands of content delivery today, we need to adopt manufacturing principles. The is made possible by content engineering: The application of engineering discipline to the design and delivery of content.
Case study: The making of The Language of Content Strategy
In this session, Scott will show us how he and Rahel created a book, an eBook, a website, and a set of learning materials, from a single source, without breaking the bank. They did it by harnessing technology and crowd sourcing.
Scott talked about the differences in approach between technologists and editorialists. Conflict and time wasting arise because of a lack of a common language. Rahel and Scott wanted to craft a solution: A crowd-sourced book about content strategy that is both a case study in content engineering and a practical example of content marketing.
The team started with careful analysis of the educational landscape, contributors, and more. Then they defined the content types they needed.
- The smallest unit of content they would create would be a term and definition pair.
- Another content type is an essay of 250 words.
- Then there are contributor bios, statements of importance, and resources.
For the authoring environment, the team selected Atlassian Confluence. It’s a wiki with support for XML content re-use.
They also chose a gimmick: 52. The project included 52 terms, 52 definitions, by 52 experts, published over 52 weeks, and one of the output formats was 52 cards.
Then they selected a team of experts: the best and brightest in tangentially-related fields.
Other roles and responsibilities: markup specialist, editor, indexer, peer reviewers, and a graphic artist.
The source data
The source was authored in Confluence wiki. The content types are clearly labelled: Biography, importance statement, topic name, definition, etc.
In the various output formats, the content is structured differently but still consists of the various topic types. For example, in the printed book every chapter is two pages long, and consistently structured. The eBook format is slightly different, as are the website format and the flash cards learning format.
Each Thursday, one chapter is automatically published. The web output also contains audio files, photos, and additional resources that are not contained in the book.
The advantages of a future-proofed content strategy
The team was able to add content after the fact, such as the audio files for accessibility. The content strategy was designed to future proof the content, so the team was able to adjust to challenges and opportunities. And the strategy is repeatable. Now that it’s been done, it can be done again.
Scott told an amusing story of how he disobeyed his own rules, and tried to create another channel by copying and pasting instead of using the single-sourced content. A marketing person asked him to create a slide deck from the content. He was on a plane, without WiFi, so decided to do it by cutting and pasting. Needless to say, this didn’t work. By the end of the flight he had only 13 slides of the required 52, and had run out of laptop battery!
The cost of the project came in at under $10,000USD.
- Approximately $4000USD forgraphic design, indexing, editing, markup assistance, audio tracks and hosting, the URL for the first year, and site hosting for a year.
- Approximately $5,440 for book donations, postage, Adobe InDesign, Confluence Wiki, and overhead/administrative costs.
Scott finished by saying that if you want to undertake a similar project, ask him. He will try to help.
This was a fun and inspiring talk. Thanks Scott!
The standard search in Confluence wiki searches the visible content of the page. It also offers keywords for some specific searches, such as macro names and page titles. But sometimes we need to find things that the search cannot find, because the content of the relevant XML elements is not indexed. This post offers a solution of sorts: Copy the XML storage format of your pages into text files on your local machine, then use a powerful search like
grep to do the work.
Here are some examples of the problem:
- We may want to find all pages that reference a certain image, or other attachment. It’s easy enough to find the page(s) where the image is attached. But it’s not possible to find all pages that display a given image which is attached to another page.
- It’s possible to search for all occurrences of a macro name, using the
macroName:keyword in the search. But it’s not possible to search for parameter values. This means, for example, you can’t search for all pages that include content from a given page.
I’ve written a script to solve the problem, by downloading the storage format from Confluence onto your local machine, where you can use all sorts of powerful text searches. You’re welcome to use the script, with the proviso that it’s not perfect.
The script is in a repository on Bitbucket: https://bitbucket.org/sarahmaddox/confluence-full-text-search.
Note: To run the script successfully, you need access to Confluence, and the Confluence remote API must be enabled.
To run the script, you need to install Python. The scripts are designed for Python 3, not Python 2. There were fairly significant changes in Python 3.
- Download Python 3.2.3 or later: http://www.python.org/getit/
python-3.2.3.amd64.msi, because I’m working on a 64-bit Windows machine.)
- Run the installer to install Python on your computer.
(I left all the options at their default values.)
- Add the location of your Python installation to your path variable in Windows:
- Go to ‘Start’ > ‘Control Panel’ > ‘System’ > ‘Advanced system settings’
- Click ‘Environment Variables’.
- In the ‘System variables’ section, select ‘Path’.
- Click ‘Edit’.
- Add the following to the end of the path, assuming that you installed Python in the default location:
- Click ‘OK’ three times.
- Open a command window and type ‘python’ to see if all is OK. You should see something like this:
Getting the script
Go to the Bitbucket repository and choose ‘Downloads’ > ‘Branches’, then download the zip file and unzip it into a directory on your computer.
Running the script to get the content of your pages
To use the
- Enable the remote API (XML-RPC & SOAP) on your Confluence site.
- Open the
getConfluencePageContentscript in Python’s ‘IDLE’ GUI. (Right-click on the script and choose ‘Edit with IDLE’.)
- Run the script from within IDLE. (Press F5.)
- The Python shell will open and prompt you for some information:
- Confluence URL – The base URL of your Confluence site. If the site uses SSL, enter ‘HTTPS’ instead of ‘HTTP’. For example:
- Username – Confluence will use this username to access the pages. This username must have ‘view’ access to all the spaces and pages that you want to check.
- Password – The password for the above username.
- Space key – A Confluence space key. Case is not important – the match is not case-sensitive.
- Output directory name – The directory where the script should put its results. The script will create this directory. Make sure it does not yet exist.
- Confluence URL – The base URL of your Confluence site. If the site uses SSL, enter ‘HTTPS’ instead of ‘HTTP’. For example:
- Look for the output directory as a sibling of the directory that contains the
getConfluencePageContentscript. In other words, the output directory will appear in your file system at the same level as the script’s directory.
Output of the script
The Bitbucket repository contains an example of the output, based on the Demonstration space shipped with Confluence. See the
outputexample directory in the repository. For example, this file contains the content of the page titled ‘Welcome to Confluence’.
The script gets the content of all pages in the given Confluence space. It puts the content of each page into a separate text file, in a given directory.
The script creates the output directory as a sibling of the directory that contains the
getConfluencePageContent script. In other words, the output directory will appear in your file system at the same level as the script’s directory.
The file name is a combination of the page name and page ID. To prevent problems when creating the files, the script removes all non-alphanumeric characters from the file name. To ensure uniqueness, it appends the page ID to the page name when creating the file name.
The content is in the form of the Confluence storage format, which is a type of XML consisting of HTML with Confluence-specific elements. (Docs.)
The script also writes a line at the top of each file, containing the URL of the page, and marked with asterisks for easy grepping.
- The script will show an error if the output directory already exists.
- If you see the following error message, you need to enable the remote API (XML-RPC & SOAP) on your Confluence site: xmlrpc.client.ProtocolError: <ProtocolError for localhost:8090/rpc/xmlrpc: 403 Forbidden>
Grep and winGrep
Now that you have the page content in text form, the world’s your oyster. You can use the full power of text search tools. If you’re on UNIX, you’ll already know about grep.
If you’re on Windows, let me introduce grepWin. It’s a free, powerful search tool that you can install on Windows. It offers regular expression (regexp) searches as well as standard searches, and it has a very nice UI (user interface).
This screenshot shows a search for an image called ‘step-2-image-1-confluence-demo-space.png’. The image is attached to one page, and referenced in two pages. QED.😀
I’d love to know if you think you’ll find the script useful, and if you have any ideas for improving it.
You got it. Avisi have developed two nifty macros to display an XML schema (XSD) in tabular and graphic format on a Confluence page. The XSD Viewer is a new add-on for Confluence wiki, and the Avisi developers are keen for input from technical writers and others interested in XML schemas.
I’ve been playing around with the add-on, so I’d love to show you a couple of examples and tell you how to get it working for yourself. I’ve also chatted with Yanne from Avisi, who says that he and his team would love to have your feedback.
Example 1: A purchase order schema
I’ve grabbed the sample schema for a purchase order from MSDN: http://msdn.microsoft.com/en-us/library/ms256129.aspx. I’ve instructed the XSD viewer to start with the
purchaseOrder element, and show a depth of 2 levels.
Example 2: Graham Hannington’s schema for the Confluence storage format
Hehe, if you put Confluence and XSD in the same blog post, then ‘twould be remiss not to include Graham’s XML schema for the Confluence storage format.😀
The XSD Viewer is using
confluence.xsd, starting with the
One point of interest here is that the
confluence.xsd file references two other schema files:
confluence-xhtml.xsd. All I had to do to make this work, was to attach all three XSD files to the page. This screenshot shows the attachments on the above page:
A couple of times, the XSD Viewer has declined to show any rows in the table. I’m not sure why this occurs. If it happens to you too, it’s worth letting the Avisi team know.
I’m using Confluence 5.0.1, with version 1.1.1 of the XSD Viewer. I’m running Confluence on my Windows 7 laptop, and I’m using Chrome to view the wiki pages.
How to get your own XSD viewer
To make this happen, you need to do the following:
- Download and install Confluence, if you don’t already have it. You can try it for free for 30 days. See the Confluence download page.
- Download the XSD Viewer add-on and install it into Confluence. The add-on is also available for free for 30 days. See the XSD Viewer page on the Atlassian Marketplace.
- Create a page in Confluence.
- Attach your XSD file to the Confluence page, just as you would attach a screenshot or other file. See the documentation on adding attachments.
- Edit the page.
- Add the “XSD Image” and/or the “XSD Table” macros to the page. See the documentation for the XSD Viewer.
- Save the page.
- The XSD Viewer page on the Atlassian Marketplace.
- The documentation for the XSD Viewer.
- A getting-started video for the XSD Viewer on YouTube.
- The issue tracker for the XSD Viewer.
Feedback so far
I’ve given Yanne at Avisi some feedback already:
- At first the error messages were a bit too generic to be useful. Avisi have already followed up on this in the latest version of the add-on, which gives more specific error messages. Great!
- Currently the macro autocomplete in Confluence is triggered by “XSD”. Suggestion: Add “schema” and “XML” to the list of triggers.
- Add the option to add a border and other styling to the image.
The Avisi team like the latter two suggestions, and are waiting for more feedback before implementing them. Would you be interested in an XSD viewer in Confluence, and what requirements would you have for it?
To mark the impending release of Confluence 5.0, we’ve applied a new style to the Confluence documentation. It’s done by means of some snazzy CSS, created by Andrew Prentice, Valter Fatia and Paul Watson.
What do you think of the new look? We’d love your feedback on the styles, the way some information is hidden until you hover over it (try zooming your cursor around the page to find the hidden bits) and the contrast with the standard Confluence 5.0 look.
Our customised styles
We’ve applied custom CSS only to the latest documentation space on the wiki – that’s the documentation for Confluence 5.0. This space is using the Documentation theme, but with a lot of CSS on top:
The standard Confluence 5.0 styles in the Documentation theme
The documentation for Confluence 4.3 is on the same wiki, but we haven’t applied the custom stylesheets. The wiki is already running Confluence 5.0, so you can see the new 5.0 look and feel without any custom styling. The space is using the Documentation theme:
The standard Confluence 5.0 styles in the default theme
Just for completeness, here’s the Atlassian Training space, on the same wiki, but using the default Confluence 5.0 theme:
How do you add CSS to a Confluence space?
It’s all in the documentation: Styling Confluence with CSS.