Blog Archives

Out of print: “Confluence, Tech Comm Chocolate”

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.

solong_300pxUpdate: Although the book is out of print, you can download a free PDF version of the book from the publisher, XML Press.

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.

The Confluence, Tech Comm, Chocolate wiki has moved to a shiny new site

The Confluence, Tech Comm, Chocolate wiki is a companion to my book about technical communication, technical writers, wikis and chocolate. This week we moved the site to a shiny new Confluence OnDemand server. Please take a look, sign up if you like, and also please consider changing any external links you may have pointing to content on the site.

The new address of the Confluence, Tech Comm, Chocolate wiki is: https://wikitechcomm.atlassian.net/

The old address was: https://wikitechcomm.onconfluence.com/

What does the move to Confluence OnDemand mean?

Confluence, Tech Comm, ChocolateConfluence OnDemand is Atlassian’s new hosted platform. Our site will now automatically get the latest and up-to-datest version of Confluence. It’s currently running an early version of Confluence 5.0! So we’ll be able to play with the latest Confluence features before anyone else. If you’re interested, keep a watch on the frequently-updated Atlassian OnDemand release summary.

My seat-of-the-pants feeling is that the new site is significantly faster than the old one. 🙂

The hosted platform restricts certain functionality, primarily add-ons and customisations of the wiki. I won’t be able to install add-ons or plugins that are not pre-approved by Atlassian. This won’t have a big effect on people using the site. We no longer have the awesome add-ons from K15t Software for creation of ePub and DocBook exports. The Copy Space plugin isn’t there either. Gliffy, for drawing diagrams, is available in Confluence OnDemand, along with the add-ons listed here: Atlassian OnDemand Plugin Policy.

Existing content, redirects, and external links pointing to the site

This bit is for the 77 people already using the wiki. 🙂 All your pages, blog posts, comments and other pieces of information are safely on the new site. Please let me know if you spot anything amiss.

Atlassian has put redirects in place. If you try to go to the old address, you should automatically end up on the new site. The old site will be decommissioned in a few weeks’ time. There’s no scheduled date for the shutting down of the redirect service, but it’s probably a good idea to update any external links you may have, to point to the new site.

The book

The book is called Confluence, Tech Comm, Chocolate: A wiki as platform extraordinaire for technical communication. It’s about developing documentation on a wiki. It’s also about technical communicators. And chocolate.

Do come and join the fun at the book’s wiki site: Confluence, Tech Comm, Chocolate wiki.

Ha ha, Atlassian is offering prizes to wiki huggers

Do you wuv your wiki? 😉 Atlassian is offering 5 prizes this week to random entries in an online competition. To enter, pick your favourite Confluence wiki feature and share it on Twitter or Facebook. I’m not eligible to win a prize because I work at Atlassian. But as a technical writer and self-confessed wiki hugger I’m hoping that a technical communicator wins on at least one of the five days!

Intrigued? Here’s the link to the competition: Get Your Wiki On. It starts on Monday 2 May 2011 and runs for the rest of the week. The time zone is California (Pacific Daylight Time) — so Tuesday morning in Sydney is still Monday. There’s a prize for each day, picked randomly from the day’s entries.

Let me know if you win!

Ha ha, Atlassian is offering prizes to wiki huggers

Raindrops on a leaf stalk

Book review of “WIKI: Grow Your Own for Fun and Profit”

I’ve just finished reading Alan J. Porter‘s new book, WIKI: Grow Your Own for Fun and Profit. I heartily recommended this book to anyone who wants to know more about wikis. In fact, you’ll enjoy it even if you’re already intimately acquainted with wikis.

The content and message of the book grow organically, rather like its subject. To get the full benefit of Alan’s experience and the full impact of his message, you need to sit down with a beverage or brew, start from the beginning and read through to the end. That’s easy and rewarding to do. The book has a comfortable conversational style. Alan introduces a topic or concept in one chapter, then builds on it in subsequent chapters. By the time you reach the end of the book, you’ve absorbed Alan’s experience of and research into wikis. You’ve also examined his useful examples, mulled over his anecdotes and chuckled at Douglas Potter’s apt drawings.

What’s it about?

The book takes you through all stages of wiki ownership, from deciding whether you need a wiki, through choosing the right one, encouraging people to use it, designing it, then structuring and restructuring it as it gains more content.

Throughout the book are ideas for encouraging people to use the wiki and to contribute content to it.

"WIKI: Grow Your Own for Fun and Profit" - drawing by Douglas Potter

Chapter 2 "Defining the Wiki" - drawing by Douglas Potter

First impressions

I love the cover of the book. Comfortable. Alternative. Man at work.

I also love the drawings by Douglas Potter. They are so cleverly suited to the style of the book. This one is my favourite, from the cover plate of chapter 2, Defining the Wiki.

Highlights

The case studies at the back of the book are particularly interesting. There are five of them. For me, these stand out:

  • Case study 5 tells the story of the book itself. The author, editor, reviewers and publisher all worked together on the book, using a wiki (PBworks) as their collaboration platform. Now that’s dogfooding the message of a book. 😉 The case study outlines the process they followed and the benefits the publisher saw in using a wiki for this purpose. Alan also gives a foretaste of the process earlier in the book, under the heading Doing it Ourselves (page 12).
  • Case study 3 tells how a company used a wiki to gain ISO 9000 certification in a very short period of time.
  • Case study 4 is Gina Fevrier‘s story of adopting Confluence wiki to engage users in her company’s document content strategy.

Some sections of the book that stood out for me:

  • User-Generated Content (pages 82-4). This section  is a must-read, for its excellent summary of the value of user-generated content, and for its anecdotes.
  • Why Would You Need to Use a Wiki? (pages 6-11). This section has a good, concise list of a wiki’s uses, based on a real-life example of a project that could have used one but didn’t.
  • Appendix D: Notes on Popular Wikis (pages 141-6). The summaries of the features and intended audiences of each wiki are concise and useful. The wikis covered are: Confluence, DokuWiki, MediaWiki, MindTouch (the erstwhile DekiWiki), MoinMoin, MyWiki, PBworks, ProjectForum, TiddlyWiki, TikiWiki and Trac.

Interesting titbits:

  • Under the heading Aren’t Wikis Inaccurate? (page 4) Alan says: “Studies have shown that the number of mistakes per article on Wikipedia is actually lower than in the venerated print Encyclopedia Britannica”.

My favourite anecdote:

  • The one about tennis balls in the server room (page 61). I won’t repeat it, because it’s best to read it in context. 🙂

In conclusion

Sit back, put your feet up, tilt back your hat and get reading. Your wiki will take root as you go.

How to copy a Gliffy diagram

The Gliffy blog gives a great description of how to copy elements from one Gliffy diagram to another. Here’s a slightly different technique, for copying an entire Gliffy diagram from one Confluence page to another. You could also use this technique to copy a diagram from one Confluence site to another.

I demonstrated this technique to a colleague recently, and I’ve decided to blog about it in case anyone else finds it useful. In summary:

  • Go to the Confluence page that contains the Gliffy diagram and download the attached file that has the scary comment “GLIFFY DIAGRAM, ONLY EDIT IN GLIFFY EDITOR!” This is the Gliffy data file.
  • Remove any extension that your browser may add to the file name.
  • Upload the Gliffy data file as an attachment to the page where you want a copy of the diagram.
  • Insert the Gliffy macro onto the Confluence page. For the diagram name, give it the name of the attached Gliffy data file.
  • If the diagram shows up as empty, open and close the Gliffy editor to jog the diagram into life.

Step 1. Download the Gliffy diagram’s data file

Gliffy stores all the information about a diagram in a file attached to the Confluence page. The attachment’s name is the name of your diagram. The comment next to the attachment lets you know in no uncertain terms that you shouldn’t mess with this data file. 😉

Here’s a Gliffy diagram displayed on a Confluence page (click the image to see a larger version):

How to copy a Gliffy diagram

This screenshot shows the Gliffy data file attached to the Confluence page:

 

How to copy a Gliffy diagram

How to copy a Gliffy diagram

 

Download the Gliffy data file onto your computer:

  1. Go to the Confluence page that contains the diagram, and select “Tools” then “Attachments” to get to the “Attached Files” page as shown above.
  2. Find the Gliffy data file in the list of attached files. The file name will be the name of your diagram. (In my case, it’s “Atlassian Plugin Development Platform”, which is a bit unfortunate because that’s also the page name. Please excuse any confusion that may cause!) The “Comment” column contains the words “GLIFFY DIAGRAM, ONLY EDIT IN GLIFFY EDITOR!” next to the relevant attachment.
  3. Right-click the file name and select “Save link as…” (or whatever words your browser uses to offer you the ability to download a file and save it on your computer).
  4. Save the file on your computer.
  5. Check the file name on your computer carefully. It should be just the diagram name, without an extension. In my case, it’s just “Atlassian Plugin Development Platform”.
    Note: Some browsers (IE, I’m looking at you) add an extension, often “.xml” or “.htm”. If that’s happened, remove the extension.
  6. If you like, you can change the file name itself, if you want your new diagram to have a different name. I’ve decided to change mine to “CopyTest”.

Step 2. Upload the Gliffy data file to another page

Now you can just upload the Gliffy data file, in the same way as you would upload an image, a screenshot or any other attachment.

  1. Go to the Confluence page where you want to add the diagram, and select “Tools” then “Attachments” to see the “Attached Files” page.
  2. Drag and drop the Gliffy data file onto the “Attached Files” page, or click “Browse” and upload the file in the usual way.

Here’s my Gliffy data file, now called “CopyTest”, attached to a Confluence page. Notice that it does not yet have the Gliffy warning in the comment column. This is because neither Gliffy nor Confluence knows at this stage that the file is actually a Gliffy file.

 

How to copy a Gliffy diagram

How to copy a Gliffy diagram

FYI, the Gliffy data file contains a lot of text. In my case, the file starts with this text:

<stage keygen_seq="71"><pageObj drawingHeight="550" drawingWidth="700"

 

Step 3. Insert the Gliffy macro onto the Confluence page

Now you just need to let Gliffy and Confluence know there’s a diagram on the page. You do that by adding the Gliffy macro onto the page.

If you’re a wiki markup fan, just copy the markup from the original page and update the diagram name if you changed it. In my case, the original wiki markup looked like this:

{gliffy:name=Atlassian Plugin Development Platform|align=left|size=L}

I have changed the name of my diagram to “CopyTest”, so I inserted the following markup onto my page:

 

How to copy a Gliffy diagram

How to copy a Gliffy diagram

 

If you prefer to use the rich text editor and the macro browser, then just supply the file name and other parameters in the usual way.

Step 4. Edit the Gliffy diagram to cement the relationship

Often, the relationship between the Confluence page and the Gliffy diagram needs a jolt to get it started! After adding the macro, you may notice that your Gliffy diagram looks empty:

 

How to copy a Gliffy diagram

How to copy a Gliffy diagram

 

Just click “Edit Diagram” under the empty box to open the Gliffy editor. Then close the editor again.

Voilà!

 

How to copy a Gliffy diagram

How to copy a Gliffy diagram

 

My environment

I’m using Gliffy 2.0.2 on Confluence 3.3.3.

Hmm, that’s quite an old version of Gliffy. I see that the latest version is 3.0.6! I’ll lodge a request to get our plugin upgraded. 🙂

Older versions of Gliffy included the page name etc in the macro data

Older versions of Gliffy used to include more information in the macro data: the space name, page name and page ID. For example, your wiki markup may look like this:

{gliffy:name=Network topology|space=DOC|page=Recommended network topology|pageid=107610617|align=left|size=L}

Note: If your version of Gliffy does this, you will need to change the space name, page name and page ID to match the new page where you have put the copy of the diagram. This is very important. If you leave them at the old values, then the new page will actually display the diagram from the original page, not from its own attachment. This can lead to unexpected results, especially when someone edits the diagram from either page.

What about JIRA?

I wonder if you could use this technique to copy a diagram from JIRA to Confluence or vice versa? Let me know if you’ve tried it.

<stage keygen_seq=”71″><pageObj drawingHeight=”550″ drawingWidth=”700″ istt=”true” print_scale=”0″ print_grid=”0″ print_paper=”LETTER” print_layout=”0″ pb=”0″ stg=”1″ gr=”1″ fill=”16777215″ height=”550″ width=”700″><styles><shapeStyle lineColor=”global:0x333333″ fillColor=”global:26112″ gradientOn=”true” dropShadowOn=”false” lineWidth=”-1″/><lineStyle end=”0″ begin=”0″ width=”1″ pattern=”0″ color=”0x333333″/><textStyle color=”0″ style=”bold=true” size=”18″ face=”Arial”/></styles><objects><object order=”0″ dshad=”false” gradon=”true” linew=”2″ linec=”3355443″ fill=”3963061″ text-horizontal-pos=”center” text-vertical-pos=”middle” lock=”false” fixed-aspect=”false” rot=”0″ height=”80″ width=”480″ y=”528″ x=”290.5″ libraryid=”com.gliffy.basic” shp_id=”2″ class=”round_rect”><text><![CDATA[<P ALIGN=”CENTER”><FONT FACE=”Arial” SIZE=”12″ COLOR=”#000000″ LETTERSPACING=”0″ KERNING=”0″><B>Atlassian Plugin Framework</B></FONT></P>]]></text><connlines/></object><object order=”1″ dshad=”false” gradon=”true” linew=”2″ linec=”3355443″ fill=”3963061″ text-horizontal-pos=”center” text-vertical-pos=”middle” lock=”false” fixed-aspect=”false” rot=”0″ height=”80″ width=”145″ y=”528″ x=”621″ libraryid=”com.gliffy.basic” shp_id=”4″ class=”round_rect”><text><![CDATA[<P ALIGN=”CENTER”><FONT FACE=”Arial” SIZE=”12″ COLOR=”#000000″ LETTERSPACING=”0″ KERNING=”0″><B>Static plugins</B></FONT></P><P ALIGN=”CENTER”><FONT FACE=”Arial” SIZE=”12″ COLOR=”#000000″ LETTERSPACING=”0″ KERNING=”0″><B>(v1)</B></FONT></P>]]></text><connlines/></object><object order=”2″ dshad=”false” gradon=”true” linew=”2″ linec=”3355443″ fill=”3963061″ text-horizontal-pos=”center” text-vertical-pos=”middle” lock=”false” fixed-aspect=”false” rot=”0″ height=”80″ width=”480″ y=”428″ x=”290.5″ libraryid=”com.gliffy.basic” shp_id=”5″ class=”round_rect”><text><![CDATA[<P ALIGN=”CENTER”><FONT FACE=”Arial” SIZE=”12″ COLOR=”#000000″ LETTERSPACING=”0″ KERNING=”0″><B>OSGi plugins</B></FONT></P><P ALIGN=”CENTER”><FONT FACE=”Arial” SIZE=”12″ COLOR=”#000000″ LETTERSPACING=”0″ KERNING=”0″><B>(v2)</B></FONT></P>]]></text><connlines/></object><object order=”3″ dshad=”false” gradon=”true” linew=”2″ linec=”3355443″ fill=”16763904″ text-horizontal-pos=”center” text-vertical-pos=”middle” lock=”false” fixed-aspect=”false” rot=”0″ height=”80″ width=”145″ y=”240″ x=”122.5″ libraryid=”com.gliffy.basic” shp_id=”6″ class=”round_rect”><text><![CDATA[<P ALIGN=”CENTER”><FONT FACE=”Arial” SIZE=”12″ COLOR=”#000000″ LETTERSPACING=”0″ KERNING=”0″><B>Atlassian REST Plugin Module</B></FONT></P>]]></text><connlines/></object><object order=”4″ dshad=”false” gradon=”true” linew=”2″ linec=”3355443″ fill=”16763904″ text-horizontal-pos=”center” text-vertical-pos=”middle” lock=”false” fixed-aspect=”false” rot=”0″ height=”80″ width=”145″ y=”140″ x=”123″ libraryid=”com.gliffy.basic” shp_id=”7″ class=”round_rect”><text><![CDATA[<P ALIGN=”CENTER”><FONT FACE=”Arial” SIZE=”12″ COLOR=”#000000″ LETTERSPACING=”0″ KERNING=”0″><B>Shared Access Layer (SAL)</B></FONT></P>]]></text><connlines/></object><object order=”5″ dshad=”false” gradon=”true” linew=”2″ linec=”3355443″ fill=”16763904″ text-horizontal-pos=”center” text-vertical-pos=”middle” lock=”false” fixed-aspect=”false” rot=”0″ height=”80″ width=”145″ y=”140″ x=”288″ libraryid=”com.gliffy.basic” shp_id=”8″ class=”round_rect”><text><![CDATA[<P ALIGN=”CENTER”><FONT FACE=”Arial” SIZE=”12″ COLOR=”#000000″ LETTERSPACING=”0″ KERNING=”0″><B>Atlassian User Interface (AUI)</B></FONT></P>]]></text><connlines/></object><object order=”6″ dshad=”false” gradon=”true” linew=”2″ linec=”3355443″ fill=”26112″ text-horizontal-pos=”center” text-vertical-pos=”middle” lock=”false” fixed-aspect=”false” rot=”0″ height=”65″ width=”105″ y=”333″ x=”103″ libraryid=”com.gliffy.basic” shp_id=”9″ class=”round_rect”><text><![CDATA[<P ALIGN=”CENTER”><FONT FACE=”Arial” SIZE=”12″ COLOR=”#000000″ LETTERSPACING=”0″ KERNING=”0″><B>Unified Plugin Manager (UPM) </B>to be included soon</FONT></P>]]></text><connlines/></object><object order=”7″ dshad=”false” gradon=”false” linew=”1″ linec=”0″ fill=”16777215″ text-horizontal-pos=”center” text-vertical-pos=”middle” lock=”false” fixed-aspect=”false” rot=”0″ height=”29″ width=”615″ y=”63″ x=”355″ libraryid=”” shp_id=”20″ class=”text_shape”><text><![CDATA[<P ALIGN=”LEFT”><FONT FACE=”Arial” SIZE=”18″ COLOR=”#000000″ LETTERSPACING=”0″ KERNING=”0″><B>Components of the Atlassian Plugin Development Platform</B></FONT></P>]]></text><connlines/></object><object order=”8″ dshad=”false” gradon=”true” linew=”2″ linec=”3355443″ fill=”16763904″ text-horizontal-pos=”center” text-vertical-pos=”middle” lock=”false” fixed-aspect=”false” rot=”0″ height=”80″ width=”145″ y=”240″ x=”288″ libraryid=”com.gliffy.basic” shp_id=”31″ class=”round_rect”><text><![CDATA[<P ALIGN=”CENTER”><FONT FACE=”Arial” SIZE=”12″ COLOR=”#000000″ LETTERSPACING=”0″ KERNING=”0″><B>Atlassian Template Renderer</B></FONT></P>]]></text><connlines/></object><object order=”9″ dshad=”false” gradon=”true” linew=”2″ linec=”3355443″ fill=”26112″ text-horizontal-pos=”center” text-vertical-pos=”middle” lock=”false” fixed-aspect=”false” rot=”0″ height=”65″ width=”105″ y=”333″ x=”230″ libraryid=”com.gliffy.basic” shp_id=”43″ class=”round_rect”><text><![CDATA[<P ALIGN=”CENTER”><FONT FACE=”Arial” SIZE=”12″ COLOR=”#000000″ LETTERSPACING=”0″ KERNING=”0″><B>Unified Application Links (UAL) </B>to be included soon</FONT></P>]]></text><connlines/></object><object order=”10″ dshad=”false” gradon=”true” linew=”2″ linec=”3355443″ fill=”26112″ text-horizontal-pos=”center” text-vertical-pos=”middle” lock=”false” fixed-aspect=”false” rot=”0″ height=”65″ width=”105″ y=”333″ x=”352″ libraryid=”com.gliffy.basic” shp_id=”44″ class=”round_rect”><text><![CDATA[<P ALIGN=”CENTER”><FONT FACE=”Arial” SIZE=”12″ COLOR=”#000000″ LETTERSPACING=”0″ KERNING=”0″><B>OAuth </B>to be included soon</FONT></P>]]></text><connlines/></object><object order=”11″ dshad=”false” gradon=”true” linew=”2″ linec=”3355443″ fill=”26112″ text-horizontal-pos=”center” text-vertical-pos=”middle” lock=”false” fixed-aspect=”false” rot=”0″ height=”65″ width=”105″ y=”333″ x=”476″ libraryid=”com.gliffy.basic” shp_id=”45″ class=”round_rect”><text><![CDATA[<P ALIGN=”CENTER”><FONT FACE=”Arial” SIZE=”12″ COLOR=”#000000″ LETTERSPACING=”0″ KERNING=”0″><B>Atlassian Gadgets </B>to be included  soon</FONT></P>]]></text><connlines/></object></objects></pageObj></stage>
%d bloggers like this: