A few days ago, our technical writing team went on a chocolate outing. This is not a rare occurrence. This time I have some pictures and a few musings about the confluence of teams and chocolate.

Concept:

Reference:

Task:

We decided that was one user guide we could all follow without difficulty!

chocolate.inspire(team)

For me, one of the most important aspects of my job is the team I work with. After all, I spend most of my waking life with them. It’s good to build up some common interests, other than the work itself, so that you have something to talk about, something to bind you together, even something to complain about.

I think fun is very important. But “fun” is a fuzzy concept. People have different ideas of what constitutes fun and technical writing teams typically consist of very disparate individuals. So how on earth do you find something that everyone will consider fun, interesting and invigorating?

Funnily enough (heh), we’ve found that it just happens. We have a great bunch of people in our team. Every one of us wants everyone else to feel good in the team. So when a possible “common interest” arises, everyone buys into it.

skate.go()

Earlier I wrote that it’s even good to have something to complain about together. Don’t we all love to exclaim in anguished tones, and isn’t it a good thing if the object of such gleeful anguish is not our job! I have a Calvin and Hobbes cartoon above my desk at work, showing Calvin’s father with a mangled bicycle, obviously the result of a bad stack. The caption reads something like:

“The secret to enjoying your job is to have a hobby that is even worse.”

Our technical writing team is keen on rollerblading. Actually, we’ve only done it once, but we plan to get out there again soon. And being keen doesn’t mean we do it well, just that we’re happy to give it a go. Or simply to watch our team mates fall off the blades! We made it into the Cherryleaf I’m a technical writer and I’m not boring annals.

But can you guess what the most popular common interest is? You got it: chocolate. And it’s not something we complain about!

chocolate.reward(jens)

We’ve taken to “rewarding” other people, those who are not fortunate enough to be technical writers, when they do something that improves the documentation. How do we reward them? With chocolate of course.

Our latest reward went to Jens, who is doing some awesome work on a “documentation” theme for Confluence wiki. (Yes, it’s true! I’ll let you know more about it when there’s a prototype ready for trial.)

We went to at Max Brenner in George Street, Sydney. Clockwise from the left, here are Rosie, Jens, Ed, Giles and Andrew (I was taking the photo):

Lucky Jens!

tShirt.glow()

Another thing we do to engender team spirit is to dress alike.

Heh, just kidding. But on this occasion, we all made sure that we wore our new Atlassian Dragon Quest T-shirts.

Warning! The shirts are very green. When we all appeared together, an involuntary gasp of horror escaped Penny, one of our QA engineers:

“My eyes, my eyes.”

So here we are, the Atlassian technical writers on a chocolate outing in our Dragon Quest T-shirts. Clockwise from the left — Ed, Giles, Andrew, Rosie and Sarah:

I count myself extremely lucky to be part of such a great team! Do you have any stories about what your team gets up to?

My article on “Using a wiki for technical documentation” appears in the October edition of Southern Communicator, the Australian and New Zealand journal of technical communication. Exciting!

A big thank you to Janet Taylor and the journal’s editorial team, both for inviting me to contribute and for allowing me to publish a PDF extract of the journal on this blog. Another big thank you to Marian Newell, who kindly gave permission for me to include her article here too. You guys are stars!

Click this link to download the PDF file containing the journal extract. Below is a summary of the content.

Using a wiki for technical documentation

My article is on pages 6-10 of the PDF file. (Printed page numbers are 4-8.) It covers the following topics:

• Overview — what a wiki is and does.
• Workflow — draft, review, publish.
• Tracking — page history, notification of updates, reverting to a previous version.
• Permissions.
• Adding structure to your documentation — table of contents, left-hand navigation bar, logical page ordering, content re-use.
• Release management.
• Agile development methodology.

(The article is based on my earlier presentation of the same name. You may find the slides and screenshots a useful adjunct to the printed article, since the images are rather small in the article.)

Trends in British technical communication

The journal’s editorial team allowed me choose another article from the journal to include in the PDF extract. I chose Marian Newell’s very interesting article, “Trends in British Technical Communication”. She discusses a number of topics, including:

• Our job titles — Are we technical writers, technical communicators, technical authors, content creators…? Personally, I prefer to be known as a technical writer. But read what Marian has to say.
• Deliverables and workplaces — printed or online content, large long-lasting projects or smaller shorter projects.
• Tools and methods.
• Generalisation and specialisation.
• Translation.
• Fads and fashions — user-generated content, social networks, information facilitators, modular content.
• Quality and productivity — Is “good enough” good enough? Should we obtain a standard qualification to put us on a par with other professions?
• Economic and commercial factors — global economic crisis, current demand, freelances and agencies, outsourcing, offshoring, remuneration, standards of written English.

And more

The PDF file also includes:

• The editor’s introduction by Sue Woolley.
• A foreword by Geoffrey Marnell about the recent ASTC and PLAIN conference, a joint event in Sydney organised by the ASTC and the Plain English movement

A beta version of the next Confluence release is out. And guess what — it’s got gadgets. This is pretty cool, so I’m jumping the gun and telling you about it right now.

It’s still just a beta release: Confluence 3.1 Open Beta. The announcement is on the Atlassian News Blog, along with an invitation to try it out. So I got myself a copy and put some gadgets onto a wiki page.

Now, the gadgets I chose are perhaps not the most useful. The most usual business case would be to add gadgets published by other Atlassian applications. For example, you might want to add a gadget that displays some information from another Confluence site or from  JIRA, Bamboo, FishEye or Crucible. (Those are other applications developed by Atlassian, the company I work for.)

But for me, the fun bit is that I can add the gadget that I created and blogged about 8 months ago.

The same 2 gadgets in 3 different applications

Here’s a screenshot of a Confluence wiki page with two gadgets. One is mine, displaying an up-to-date list of recent blog posts about technical writing from WordPress.com. The other gadget was created by Donna, our support diva, showing recent entries in a Jive discussion forum. (Click the image to enlarge it.)

Gadgets on Confluence wiki pages - oh, and in JIRA and iGoogle

Here are the same two gadgets on my iGoogle page:

Gadgets on Confluence wiki pages - oh, and in JIRA and iGoogle

And here they are in JIRA:

Gadgets on Confluence wiki pages - oh, and in JIRA and iGoogle

How do you add a gadget to a Confluence page?

Your Confluence page can display two types of gadgets:

• Internal — These are gadgets published by the same Confluence site as where they are displayed. Typically such a gadget would display information sourced from the Confluence site, such as an activity stream or a search function.
• External — These are gadgets published by another Confluence site, or a JIRA site, or even something totally different like Remember the Milk, a hamster in a wheel or a pet monkey.

If your gadget is external, the Confluence administrator needs to add the gadget to the list of available gadgets before you can add it to your Confluence page. This needs to happen only once for each gadget.

To make an external gadget available in your Confluence site:

1. Log in as a Confluence administrator.
2. Go to ‘Confluence Admin‘ and click ‘External Gadgets‘ in the left-hand navigation panel.
3. Paste the URL of your gadget into the field labelled ‘Gadget Specification URL‘. The URL should point to the XML file that describes the gadget.

For example, take a look at the URLs for the two gadgets in my screenshots above. The URL for the WordPress gadget is:

http://hosting.gmodules.com/ig/gadgets/file/117695765658379330528/
WordPress-dot-comRSSFeed.xml

And the URL for the Jive forums gadget is:

http://confluence.atlassian.com/download/attachments/203394872/forums.xml

Friendly warning: I’m just using my gadget as an example here. It’s a total hack, so please don’t insert it into any Confluence sites that matter! You’ll get all sorts of weird display problems, plus potential security issues too.

To add a gadget (external or internal) to a Confluence page:

1. Create a new page or edit an existing page.
2. Put your cursor in the edit box where you want the gadget displayed.
3. Click the ‘Insert/Edit Macro‘ icon  in the toolbar.
4. You’ll see the ‘Select Macro’ popup window. Enter some text into the search box at top right, to find the gadget you want.
   
5. Click the gadget you want. You’ll see a preview of the gadget. Most gadgets also offer you some options to configure the gadget, such as width of the display, background colour, etc.
   
6. Change the settings if you like, then click ‘Insert‘.
7. Save the Confluence page.

Extra authorisation step (OAuth)

Some gadgets require extra authorisation, to reassure the publishing server that it’s OK to send its data to the server where the gadget is displayed. Gadgets use an authorisation protocol called OAuth. There are two parts to the authorisation, one performed by the administrator and one by the person adding the gadget to or viewing the gadget on the page.

1. The administrator needs to set up the OAuth relationship between the gadget publishing server (called the provider) and the displaying server (called the consumer). This authorisation step needs to happen only once for each site. Once you’ve authorised one server to send information to another server, then you can add multiple gadgets from that server. For example, let’s say you want to display JIRA gadgets on a Confluence page. Your JIRA server needs to trust your Confluence server. So you’ll need to add Confluence as an OAuth consumer in JIRA. To do this, you will give JIRA the URL of your Confluence server. The instructions are in the JIRA documentation.
2. When you add a gadget to a page, you will need to authorise the display of information under the authority of your user ID. Similarly, every user who views the page will need to authorise the display of the information under their user ID.  The authorisation lasts for a while (a week or so, unless you revoke it). The gadget will display a ‘Log In and Approve‘ button. When you click the button, you will go to the login page of the site concerned. Log in and then approve the gadget’s access to the server’s information. Now you’ll see the gadget information displayed. There’s a full write-up in the Gadgets documentation.

Phew, I’m glad we’ve got that out of the way!

Would you like to try it yourself?

The Confluence 3.1 beta release is out, so you can hack away. If you’re very brave, you could even write your own gadget and put it on a Confluence page!

Great news from our partner. Atlassian has been named by IDC as “10 Innovative Applications Companies under $100M to watch“.  Atlassian has exemplified herself in the following key trends in applications:

• Acceleration of software as a service (SaaS), business process outsourcing (BPO), and open source over traditional on-premise software

• New business models for software use by service providers (software-within-a-service)

• Web 2.0-like functionality moves into the enterprise (e2.0).

Another great news is that Atlassian has moved up ranks in this year’s Gartner’s Magic Quadrant for Social Software in the Workplace. The report cites

Atlassian is a Challenger because it has demonstrated the ability to penetrate a global market with its popular wiki functionality…

Both news are good recognition of Atlassian’s good business strategy and effort to deliver good & useful applications to the world.

For our clients on Confluence and JIRA, you can rest assured that you are on a leading platform and expect more useful & interesting features in time to come.

I’ve just come across a new plugin developed by 224 team. It provides a Confluence macro that lets you embed a Google Wave into a Confluence wiki page. I’ve just got back from holiday, so I haven’t played around with the plugin much yet. But I’m blogging about it so that more people can try it out too. It’s cool to see this sort of development happening and even to get involved in the early stages.

A friendly warning: The plugin is pretty new, so it’s best to try it out on a test installation of Confluence.

To install the plugin:

1. Download the JAR file from the link provided on the 224 team page (at time of writing, the link is here) and save it somewhere on your computer.
2. Open Confluence in your browser and go to “Confluence Admin”.
3. Click “Plugins” in the left-hand menu.
4. Click “Browse” and find the JAR file that you saved in step 1. Select the file.
5. Click “Upload”. You should now see the “wave” plugin listed on the page, in the middle and slightly to the right of the words “Installed Plugins”.

To embed a wave onto a wiki page:

1. Create a new page or edit an existing page.
2. Add the {wave} macro, including the URL of the wave you want to embed. You can add the macro by typing the wiki markup or by using the Confluence macro browser. The format is:
   {wave:url=my.wave.url}

I decided to add my wave within a {panel} macro, to make it look a little neater. Here’s the code I used (but it’s a private wave, so you’ll need a different wave URL):

{panel}
{wave:url=https://wave.google.com/wave/#restored:wave:googlewave.com!w%252BFelxosoIC.2}
{panel}

Once I’d added the wave to my Confluence page, I replied to one of the segments in the wave on the Confluence page. See the segment that starts with “I’m replying via the Confluence plugin”:

Google Wave on Confluence wiki pages

Then I had a look at the same wave in the original Google Wave client. Ta da! My reply appears there too:

Google Wave in Confluence wiki pages

So you can take part in a wave from within Confluence. Awesome. Once I’ve found a chocolate plugin, why would I ever need to leave Confluence?

The developers of the Confluence Wave plugin say that they have great plans for the plugin. They’re inviting discussion on the Confluence feature request and on the 224 wave page. If you have a Google Wave account, you can even join the 224 team wave. Fun!

Ten ways of Web 2.0 strategies base on Mr Dion Hinchcliffe concept, I have made a web diagram for the following ways:

1^st: Back to the basics: Your Web site

In the rush to experiment with social media, community features, and sophisticated online services, it’s safe to say that some companies have lost focus. Build a rich, cleanly designed and useful Web site for your customers and they will come. As well, technical skills are still valuable despite the emphasis on “easier” Web development tools.

2^nd: Web development frameworks (browser, front-end)

Several popular tools: Adobe Flash, Adobe Air, Microsoft Silverlight, and to a certain extent, Java. These tools have reduced the gap between what your computer and your browser can do, make writing code much faster, Web-based, rich, line-of-business applications that we can use now taking lesser time to build compare in the past.

3^rd: Web development frameworks (browser, back-end)

“We are now seeing a clean break from what has come before to develop scalable, secure applications and services with Web 2.0 best practices,” Hinchcliffe says.

He cites Python and Ruby on Rails (both free) as two top programs. “We call these productivity-oriented frameworks because they can be 10 to 20 times more productive in developing code than older technologies,” he says. “That is enormous because when you are developing software, talent is most of the cost.”

4^th: Collaboration Software

Microsoft’s collaboration software, Sharepoint, which in its early days was a simple document sharing tool, is now chockfull of social networking features, including tools to support blogs, wikis, and a robust interactive community. It’s free version, Windows SharePoint Services, which comes with Windows, you can do BI, reporting, and integration, and it’s an entire application development platform as well.

Google Docs can easily do all the basics, including making bulleted lists, sorting by columns, adding tables, images, comments, formulas, changing fonts and more.

If you want to work and share docs within the team, now every team members can view and make changes at the same time. There’s an on-screen chat window for spreadsheets, and document revisions show you exactly who changed what, and when. We can also add in more details or comments.

Users love the tool because it consolidates information from many applications, and loves it because it’s a single technology they can use for many purposes.

5^th: SaaS

Software-as-a-service (SaaS) keeps growing and growing and growing, experts and analysts say, with many large companies adding SaaS components to on-premise software installations. Salesforce.com, considered the bellwether of the SaaS industry, reported record revenue of $305 million, up 23% from 2008, in its fiscal first quarter ended April 30, 2009. SaaS is winning favor because it’s often 20% cheaper than managing a non-premise application. SaaS is on track to be the dominant model for software by 2012. There are still lots of security issues, but the economics are definitely there. The other sweeping advantage is the flexibility that companies gain by rapidly adding new functionality. The paradigm shift is where you can go acquire a piece of what you need and assemble that into the software that you already own.

6^th: Cloud computing

It’s only a matter of time before cloud computing gains its place on center stage.

Sure, there are still security and reliability issues, but what aspect of IT doesn’t have that today?

Cloud services, offered by tech giants such as

• Google
• Amazon
• Microsoft
• Salesforce

They are making it relatively painless and certainly cheaper for a company to add infrastructure than if they were doing it themselves. They also gain best practices from the cloud provider. If the company decides it doesn’t need that extra infrastructure in six or 12 months, it simply cancels the service. That’s why enterprise customers are now doing cloud computing pilots, whereas a year ago, CIOs were turning up their noses at the concept.

7^th: Micro-blogging

Using social networking sites to broadcast news and other information about your company is a pretty darn cheap and widely acceptable way to engage with your community of partners, customers, and prospects. From the IT management side, there’s not much to do and why not educate your executives about the social Web?

“It’s virtually free, except for the labor involved, and you have unprecedented reach into decision makers,” says Jonathan Jaffe, founder of its-your-internet.com, a New York City-based company that advises organizations on technologies for online marketing.

This will change because as more people use Twitter these individuals will get bombarded, but now there’s a lot of accessibility. IT people are also broadcasting technical problems to the social Web and sometimes getting answers within an hour or two from vendors and experts.

8^th: Internal social networking

Companies are best off starting internally when experimenting with social media. For one thing, it’s better to make a mistake inside the company than with customers and influencers. For another, employees increasingly prefer to communicate via social media, and now, enterprise social networking tools incorporate security and other requirements that big companies seek.

Leading Web-based applications for internal blogs, micro-blogging, mashups, and wikis include Confluence by Atlassian, Socialtext, and the open-source MediaWiki. Such tools are often available at a fraction of the cost of traditional collaboration products (from companies such as Microsoft and IBM).

9^th: Bridging the gap between developers and finance

This isn’t a technology but a strategy; IT pros should stay close to the people who hold the purse when they are looking into new applications and projects, as always.

“From my point of view, having developed Web applications for the past 13 years, a key issue I’ve seen everywhere is the communication gap between the financial controller (FC) of the company and the development team members. So my advice is don’t focus too much on the buzzwords. Get in synch with your FC and look at your projects from a business point of view.” Dan Bridge, a UK-based developer

10^th: Thinking small

• The beauty of Web 2.0 is that you don’t have to invest loads of cash or time to experiment.

• Small projects are often the way to go. In fact, one might say that in today’s world of layoffs, small is big.

• Check out all the social media tools and sites that you can and then consider: Could any of these ideas work in-house or on our public site?

While I was doing the Atlassian Dragon Quest challenge, I was wondering what makes it look such a complicated effort. Hence I made the diagram below – using Gliffy Confluence Plug-in – to get a better map of mainly the configuration steps:

This picture does not show the steps which are to do with:

1. Creating the sample data – users, groups, projects, etc – required for getting the final JIRA dashboard.
2. Also the configuration of the JIRA Dragons dashboard with the necessary gadgets.

Other steps can be broadly classified into the following types which are shown by different colors in the picture:

1. Creation of configuration of the DB of the different products & their data sources. The SCM data source is also shown in same color but it is different from DB data source.
2. Enabling Crowd authentication so that SSO is enabled for different products.
3. Making Bamboo, Fisheye/Crucible and Confluence to trust JIRA and JIRA to trust these applications. More about these in a separate post – on OAuth and Trusted Application mechanisms.
4. Installation & configuration of plug-ins. Fortunately most plug-ins are bundled with JIRA & other products except for Greenhopper. More about these in a separate post  where I will try to find out the product-to-product integrations enabled by these plug-ins.

I wish I had a picture like this when I started this quest, hope it helps others in doing it faster.

Atlassian has spruced up their ALM offering with the major 4.0 release of JIRA. With this release, they have made JIRA as the single point of integration of their products – at least from a UI perspective !! I got interested in trying out the new release and also their other products. The main reason being that I have been using Confluence & JIRA for the past 2 years and I also got interested in easing the pain of Application Lifecycle Management (ALM) especially after seeing people maintaining legacy application and business processes, in the last 3 years for a major US Telco!!!

ALM and the Atlassian Products

I have used the OpenUP process and the roles people play in carrying out the activities in the 4 major phases.

1. During the inception phase , Project Manager (PM), Business Analyst (BA) and Architects (Archs) in consultation with the Stake-holders (SHs) come up the scope of the project and the initial architecture, which the SHs are willing to fund. Relevant Tools: As the scope is more or less defined using high-level functional & architectural requirements, the main tool support required is requirements tracking. Couple of extension – synapseRT for JIRA & Teamwork for Confluence seem to do this, but their features are not evaluated in this post.
2. Initial modeling & prototyping is done by the Architects and Design Engineers (DEs) during the Elaboration Phase. This is done as proof-of-concept of initial architecture & design. Relevant Tools: This phase requires software design modelling using UML or other domain-specific notations. Gliffy extension & open source Graphviz extensions for Confluence. These features will be evaluated in a separate post.
3. Construction phase involves the  implementation of working software which realizes the requirements & design set in the previous phases. This phase becomes iterative since the requirements are refined through periodic feedback from SHs. Relevant Tools: Construction phase is most done thru’ mainly an IDE. Atlassian has connectors for Eclipse & IDE and the features available in them are not elaborated in this post.
4. Transition phase encompass the V&V of the produced software through user acceptance test cases definitions and final deployment in the production environment. Testers, build & release engineers play their part in this phase. Relevant Tools: As part of requirements validation activity, SQAs require test case definition, capture & traceability of test cases to requirements. These features are available in Teamwork extension to Confluence but not evaluated in this post.

Evaluating Jira 4.0 & other 5 products – Jira Greenhopper plug-in, Crowd, Confluence, Fisheye+Crucible & Bamboo meant installation & configuration of these products to make them work together. Fortunately there is detailed documentation available as part of Dragon Slayers contest !!

I was already running JIRA & Confluence on JBoss since I was using $5 for 5 users license since April. So I had to only upgrade them to the latest versions. I used Tomcat for running the other component products – Crowd, Bamboo.Fisheye+Crucible run in their own packed container. But all products used MySQL for backend DB.

Some points to remember during the upgrade or new installation:

1. “Crowd versions 1.1 and later include CrowdID. Installing Crowd, as described below, will also install CrowdID.”, which is mentioned here
2. While upgrading JIRA make sure to remove the Javascript/JSP page cache in the Jboss/Tomcat container work directory: server/default/work
3. While importing users & groups from JIRA into Crowd, the group memberships were NOT imported !! It does matter because without the logging user being part of confluence-users group, he/whe will get the “Not permitted” message & won’t be able to see any wiki page. The same with Jira.
4. Make sure to add the connector attribute URIEncoding=”UTF-8″ , otherwise the spaces in install path of Tomcat will create problem while defining JIRA Server in Bamboo configuration.

Some points for improvement:

1. Integ. Crowd requires copying of crowd client jar files & editing properties & xml files. But the implementation in Fisheye avoids some of these manual config files editing and this should be replicated in other product components.
2. Administering the 6 different products in separate web pages will be tedious. If the products are configured for ALM, one should be able to avoid many manual steps by providing a ‘Unified Admin Interface’.

Conclusion:

If a customer is willing to buy all the products for their ALM usage, Atlassian would serve the customers better by offering an integrated ‘ALM product’ which simplifies everything – right from installation, administration & usage by a user in a specific role in the SDP. Of course, the offering of OpenSocial gadgets in JIRA is a good starting point for this ultimate goal !!

You may think you have problems, with the odd misplaced apostrophe or errant semi-colon in your documents. Well, there are dragons prowling around mine, and tweeting dragon slayers too!

A few weeks ago some smart Atlassians had the idea of making it feel like fun to set up a number of our applications as an integrated Atlassian suite. (I work at Atlassian, makers of Confluence wiki, JIRA bug tracker, and other applications for software developers.)

We’ve known for a while that it’s, uh, difficult to integrate our apps. In fact, people have used somewhat stronger words to describe the process. The problem is that the applications were developed separately, and not originally intended to talk to each other. But now we’re working towards providing an integrated platform. So, a group of Atlassians mused, why don’t we turn the setup task into a challenge and offer our doughty customers and other brave souls a reward when they get to the end?

And so the “Here Be Dragons” project was born. At heart it’s a set of documents that leads people, or “dragon slayers”, through the process of integrating six Atlassian applications. It’s also a quest, where the hero acquires better armour and more strength as he passes each of the eight stages. And behind the scenes it’s serious stuff, because it’s given us a good idea of exactly what we need to improve to make the integration process painless.

The documentation

We needed a stalwart set of documents to lead people through a typical installation and integration process, with detailed step-by-step instructions and even exact values to put into each configuration field. The idea is that people can set up their suite and get it working on the basic configuration, and tailor it later to their specific needs. I was the lucky technical writer given the job of writing the documents. It’s been a lot of fun, a lot of hard work, and one of the most unusual documentation jobs I’ve ever done.

It was a collaborative effort, with me writing the documents, testing each step in Windows as I went along and making deductions about the UNIX steps. Other people moved in to test the UNIX side of things. Jason from our Design team did the awesome art work for the documents and the T-shirt. Yes, of course there’s a T-shirt! Other technical writers, QA people and product managers contributed their knowledge of specific applications. Now Charlie the Dragon Slayer lives and breathes. (“Charlie” is the affectionate name given to the dude in the Atlassian logo. He also plays a major part in the Dragons documents.)

Twitter integration in the documents

I also added Twitter to the mix. Each page of the “Here Be Dragons” document offers our dragon slayers the chance to tweet their status, and pre-populates the tweets with suggested words. It was great fun composing the tweets and it’s even more fun now, watching the tweets pop up in the Twitter stream.

On Thursday morning a few brave souls and true had already started out on their dragon quest:

I got dragons and tweets in my documents

Pre-populating Twitter tweets

You can set up a hyperlink for people to click, that will open Twitter in their web browser and put some words into their Twitter message. If they haven’t yet logged in, Twitter will prompt them to log in. They can choose to edit the words, or just leave them as they are. They then send the tweet by clicking the Twitter “Update” button as usual.

All you need to do is add an HTML link pointing to the person’s Twitter “home” page and specifying a “status” parameter in the URL. Something like this:

<a href=”http://twitter.com/home?status=Hallo World”>Say hallo to the twittersphere</a>.

Here it is as a link:

Say hallo to the twittersphere.

If your message includes funny characters like a # sign, then you will need to URL-encode the message. For example, if you wanted to pre-populate a tweet with “Hallo World #testing” you would use this:

<a href=”http%3A%2F%2Ftwitter.com%2Fhome%3Fstatus%3DHallo+World+%23testing”>Say hallo to the twittersphere</a>.

Here’s a web site that will URL-encode your text for you.

Is “Here Be Dragons” really technical documentation?

Yes it is. The quest, tweets and pretty pictures happen around the edges. The central part of each document is hard-core technical how-to.

Scott Nesbitt has written an interesting post on the DMN blog about making user documentation more usable and user friendly. A dragon quest is a bit extreme, and it’s not something you get the opportunity to do often. But I agree with Scott that there’s a place for a lighter touch in much of the online documentation we write. It’s a delicate balance. On the one hand, it’s important that the writing style does not annoy or offend the reader and does not detract from the content. We also need to be aware of people whose first language is not the one we’re writing in. On the other hand, the occasional touch of humour or personality can focus the reader’s attention onto the page.

Dragons was a fun project. My other technical documentation assignments will seem a bit tame for a while.

Back in July, I was lamenting that I missed Atlassian’s Stimulus Package. It’s back (thanks Brian!) and with a vengeance: their Starter “program” provides $10 licenses for full blown Atlassian awesomeness (JIRA, Confluence, Crowd, Bamboo, FishEye and GreenHopper), and you can also purchase support. Additionally, JIRA 4 is out.

OpenSocial will be integrated in issue management tool Jira 4.0 released by Atlassian tomorrow; http://j.mp/1vhnWL

Over the past couple of weeks I’ve had the chance to experiment with WebWorks ePublisher, a set of tools that converts documents from Word, FrameMaker and DITA XML to a number of different output formats. One of those output formats is Confluence wiki. It’s been very interesting, so I thought I’d blog about it and see if anyone else wants to give it a go as well.

I started off knowing a bit about what ePublisher can do, having attended a WebEx demo. But I had never used it. This was such fun! Most of this blog post is going to look like a “how to” guide, because I’m hoping it will be useful to people who want to try this tool too.

A quick introduction to ePublisher

ePublisher is not a Confluence plugin. It is a set of standalone tools that can publish to Confluence as one of the output destinations. ePublisher allows you to transform content from Word, FrameMaker or PDF into a number of different output formats, including Confluence. It also provides a number of styling and design options for you to tailor the output documents.

These are the three components of ePublisher:

• ePublisher Pro – Use this component to design your “stationery” i.e. the appearance of the documents that ePublisher will output.
• ePublisher Express – Use this component to generate your documentation.
• ePublisher AutoMap – Use this component to automate the documentation generation process, and to perform batch processing, scheduling, etc.

The Evaluator Guide is in the form of a video tutorial.

Requirements

Because I wanted to convert my documents to Confluence wiki, here’s what I needed:

• Confluence version 2.10.2 or later. I’m using Confluence 3.0.
• Confluence remote API and XML RPC API enabled.
• The Content Formatting Macros plugin for Confluence, created and maintained by Adaptavist. This is a free plugin. You can install it directly from the Confluence administration console. (Instructions below.) The plugin is not officially supported by Atlassian, but is supported by Adaptavist.
• If your input documents are in Word or FrameMaker format, then you will need Word or FrameMaker installed on your machine. Supported formats are:
  • Microsoft Word 2000 to Microsoft Word 2007.
  • Adobe FrameMaker 6.0 to Adobe FrameMaker 8.0. I don’t have FrameMaker, so I didn’t try this out.
  • DITA XML 1.0 and 1.1.
  • In addition, for DITA input documents you will need the Java Development Kit (JDK) 1.4.2 or later. I have Sun JDK 1.6. You need this for Confluence too, so if you’ve already got Confluence you’re cool.

Install ePublisher and Confluence

Download WebWorks ePublisher and install it. I was using a full version of ePublisher, complete with all three components. If you’re looking for a trial version, you can try out the ePublisher Express part of the product for free.

Download Confluence and install it. You can get a free 30-day trial licence or a free personal licence.

Set up additional requirements in Confluence

1) Install the Content Formatting Macros plugin into Confluence. Step by step: Open the Confluence ‘Browse’ menu and select ‘Confluence Admin’. Click ‘Plugin Repository’ in the left-hand panel. Find the ‘Content Formatting Macros’ and click ‘Install’. Wait a while for the process to complete. It will eventually say “Installed” in the table next to the macro name.

2) Enable the remote API in Confluence. Step by step: Click ‘General Configuration’ in the left-hand panel of the Administration console. Click ‘Edit’ and click the ‘ON’ radio button next to ‘Remote API (XML-RPC & SOAP)’. Save the change.

3) Create the Confluence space where you want to put your documents. I gave my space a key of ‘TESTEPUB’. Note that you must create the space in Confluence before you deploy content to it via ePublisher.

Here’s my space:

ePublisher for converting documents to Confluence

Use ePublisher Pro to design the styles and format for your output documents

You will start off with a template created in the original software for your input document(s). For example, if your input documents are in Word, then you will import your Word template into ePublisher. If you also have input documents in FrameMaker then you will need a FrameMaker template to import into ePublisher.

Hint: For a quick start, if you don’t have a Word template you can just use the Word document you want to convert as your template. That’s what I did.

You will import your template(s) and/or sample document(s) into ePublisher Pro. ePublisher Pro will analyse the styles in the imported documents and provide you with a list of styles. You will then map the styles to your requirements for your output documents.

1. Open ePublisher Pro and create a new project. When you create the project, you will also define the output target. Because I wanted to create Confluence wiki pages, I selected “Wiki – Confluence” as my target. (You can add other targets later too, via the “Manage Targets” menu option.)

ePublisher for converting documents to Confluence

2. Add your templates or sample documents to the new project. You can do this as part of the create-project procedure. Or you can do it afterwards, by clicking ‘Project’, ‘Add Document’.

ePublisher for converting documents to Confluence

3. ePublisher Pro will scan your documents and extract all the styles, putting them into your new project.

4. Now you can map the styles from the input documents to the styles you want for your output documents. In ePublisher Pro, click the ‘Style Designer’ icon in the top tool bar. (When you move your mouse over the tool bar icons, a prompt appears in the status bar at the bottom to tell you what the icons mean.)

5. You will see a list of the styles extracted from your input documents, categorised into groups like paragraph styles, character styles, table styles etc. You can also add new styles, by clicking the ‘New Style’ icon (a tick mark) in the styles toolbar.

For each style, there are two tabs: the ‘Properties’ tab and the ‘Options’ tab. This is where you can determine your output styles, and also things like page breaks via ‘Page Break Priority’ (e.g. start a new page for each heading level 1) and table of contents levels.

ePublisher for converting documents to Confluence

ePublisher for converting documents to Confluence

6. Save your style definitions by choosing ‘File’, ‘Save as Stationery’.

ePublisher for converting documents to Confluence

That’s the ePublisher Pro part of the process done, i.e. the design work that will often be done by specialised designers. Now you can put on your document publisher hat and start converting your documents.

Use ePublisher Express to convert your input documents to the chosen output format(s)

1) Start ePublisher Express.

2) Create a new Express project. When it prompts you for stationery, select the stationery that you created from your input document templates earlier.

ePublisher for converting documents to Confluence

3) Add your input documents. You can do this while creating the project, or later via ‘Project’, ‘Add Document’. I did it by dragging the documents from my Windows file explorer into the ePublisher Express window.

Hint: When dragging and dropping, you need to drop the documents directly into the folder in the Express ‘Document Manager’ panel, not just into the panel itself.

ePublisher for converting documents to Confluence

I added a number of Word documents, and also a DITA document just for fun. I used the DITA sample document from project Gutenbert: 20,000 Leagues Under the Sea by Jules Verne. I simply dragged the ‘ditamap’ file into my ePublisher Express project. Here’s the result:

ePublisher for converting documents to Confluence

4) Next I needed to tell ePublisher Express what output format I wanted. I did this by adding a ‘Deployment Target’. Step by step: Click the ‘Target Settings’ icon in the ePublisher Express toolbar, then click ‘Add deploy target’, then ‘Add’. Select ‘Wiki – Confluence’ then ‘Edit Configuration’. A popup dialogue now asks you for the location of your Confluence site and the space key. This is the wiki space where your documents will end up. I entered the URL of my Confluence wiki (http://localhost:8080) and my space key (TESTEPUB):

ePublisher for converting documents to Confluence

After adding the new deployment target, I selected the Confluence target in the ‘Deploy to’ field as well:

ePublisher for converting documents to Confluence

5) Now for the fun part! I clicked the ‘Generate All’ icon in the ePublisher Express toolbar. Sure enough, the generation process started:

ePublisher for converting documents to Confluence

6) Antici… pation!Excitement! I kept flipping between my ePublisher window and my Confluence screen, to see the wiki pages appear.

Duh! This is where Sarah calls herself a “banana”.

I hadn’t realised that there’s another step required if you are publishing your content to a wiki. The generation process produces the output files, containing wiki markup, CSS and your text. Then you need to deploy the content to the wiki. I tried various configurations, then gave up and called WebWorks for support. That support WebEx session must be the shortest in history.

7) Deploy your content to the target — In ePublisher Express, click ‘Target’ then ‘Deploy’:

ePublisher for converting documents to Confluence

Yippee! My pages appeared in Confluence. If you leave all the design settings at their defaults, as I did, then you get a table of contents page and some neat navigation buttons at the top of every page. Here’s the automatically-generated table of contents page:

ePublisher for converting documents to Confluence

For my quick and dirty experiment, I exported some of the Crowd documentation pages from Confluence to Word, then pushed them through ePublisher to put them back into Confluence. Here’s one of the resulting pages back in Confluence:

ePublisher for converting documents to Confluence

And here’s a page from the Jules Verne DITA document, in the same Confluence space:

ePublisher for converting documents to Confluence

What happens when you update or comment on wiki pages?

After deploying my pages to Confluence, I updated a page in Confluence and also added a comment to the page. Then I redeployed the content from ePublisher.

When you deploy your content from ePublisher, it updates any existing pages with the content from the ePublisher source document. In effect, if you have updated the page in Confluence, your change will be overwritten by the ePublisher deployment. The page history retains every version of the page. The comments on the wiki page remain untouched. (This is as you would expect, because ePublisher uses the Confluence API to apply the updates.)

There is no “round trip” option available, i.e. you can’t update the pages in the wiki and then export the updates back to your source documents via ePublisher. The tool is intended for people who use Word, FrameMaker or DITA as their primary authoring environment, or people who want to convert their documents to wiki format permanently.

Conclusion

This was a rough-and-ready test, because I didn’t have time to set up my own templates or design stationery to make my output pretty. Even so, it was easy to push my Word and DITA documents through to Confluence and to produce a wiki documentation set that has a consistent format and navigation. Apart from my “banana” moment, the process was quick and painless.

I’d like to spend more time exploring the setup of the templates and of the stationery, to see how I can refine the output and tailor the Confluence pages to a specific style. Just examining the options available in ePublisher shows that it has a lot to offer in this respect. Alas, I don’t have time right now, and I wanted to blog about how far I’ve got without waiting til I do have time.

I’d also like to explore ePublisher AutoMap, which lets you automate the generation and deployment processes. This means that you can schedule batch jobs to tackle large volumes of documentation and to do the conversion on a regular basis.

I hope the above step-by-step guide through my experiment will be useful to anyone who wants to try ePublisher with Confluence. This tool will be very useful to people who have a large set of legacy documents that they want to convert to wiki format, or people who want to author their content outside the wiki on an ongoing basis, and convert it regularly to wiki as well as other formats. Single-sourcing of content is great for environments where different readers or customers need their documentation in different formats.

More information

WebWorks are holding a Round Up ‘09 conference in Austin on 19-21 October. There’s sure to be lots of information there, about using and publishing to wikis, social documentation and other interesting stuff. Wish I could be there too!

Bill Arconati wrote a post on the Atlassian blog, describing the demo the WebWorks guys gave us, including a video of the session.

Let me know if you decide to give it a go, and whether the step-by-step guide above was useful. If you get further into the templates, stationery and AutoMap side of things before I do, I’d love to hear your experiences too.

This is the blog of a 25-year-old bookmark. I proudly boast my own Hallmark serial number, 95 HBM 80-1. You’ll probably want to read all about me and my Travelling Companion (the TC) .

Today’s travel notes

The other day I dozed off inside a good book and woke up to find myself at the Atlassian office in Sydney. What on earth is Atlassian? The TC rabbits on about them all the time. Evidently they’re the guys who make Confluence wiki, JIRA bug tracker and some other equally odd-sounding things.

A little bird tweeted that Atlassian are making some big announcements next week. This worm was there during the busy run-up to the big day.

My impressions? Beer fridges, everywhere.

Word of the day: Standup.

Travel tip

When you visit Atlassian in Sydney, remember there’s an upstairs too. That’s where the TC hangs out. Take her some chocolate and your welcome is assured.

Recommended restaurant

Peace Harmony, corner of Erskine and Sussex streets, about 5 minutes’ walk from the Atlassian office. It’s a vegetarian Thai restaurant. The TC raves about the tasty food, the peaceful atmosphere and the outstanding service.

The book I’m in

The Linnet Bird, by Linda Holeman.

The photos

Me inside Atlassian, getting pally with Charlie. He’s the weird looking blue dude with his arms in the air, holding up a saucer (or whatever):

Travelling Worm goes to Atlassian

The Atlassian offices are in the old Corn Exchange building, near Darling Harbour in Sydney:

Travelling Worm goes to Atlassian

Here’s a closer view. The JIRA team is right behind this window:

Travelling Worm goes to Atlassian

Back inside now, this window lights the FishEye/Crucible team:

Travelling Worm goes to Atlassian

Charlie is a bit of a clothes horse. He gets dressed up in various outfits and then hangs around the meeting rooms or Atlassian events, all primped and proper. Here’s me chatting him up. He’s dressed for the board room, where the occasional game of poker happens too:

Travelling Worm goes to Atlassian

Me and Charlie outside the Fishbowl meeting room:

Travelling Worm goes to Atlassian

Me and Charlie in the area of the engineering and product management chiefs. Their desks look out on a gym, so Charlie feels comfortable in less formal attire:

Travelling Worm goes to Atlassian

I doff my mortarboard to Jason of the design team for his endless inventiveness in Charlie’s wardrobe.

Guess what? Hand was there too. You remember Hand, the annoying creature who attached himself to the TC when we were in Surfers Paradise last year. He’s an intrusive fellow with a finger in every pie. So it was no surprise when he insisted on attending a standup at Atlassian. A standup is a weird ritual practised by ‘agile’ programmers. This worm doesn’t think they look particularly agile, loitering around in a circle and uttering the odd technical phrase every now and then.

Here’s Hand getting underfoot at a standup. The feet are attached to the technical writing team:

Travelling Worm goes to Atlassian

Can you guess which foot belongs to the TC?

That’s all for today dudes.

After a couple of days of running into dead ends, I am finally able to drive JIRA via its SOAP interface sanely from something other than Java in an effort to automate small, repetitive tasks that are best left to tools. Without going into the details of what is it that I needed to get accomplished (which is not the key point of this post), I wanted to share a bit of the experience before I close shop for the day.

First, check out Igor Sereda’s presentation on JIRA Client, which offers many insights on general client-side JIRA programming. Second, have the JiraSoapService javadoc handy. Given the usual needs I deal with, I use Python quite a bit, which has served me very well for nearly the last 10 years, and it’s the workhorse of my tool development. But in this case, I ran into problems at almost every turn: SOAPpy cannot deal with dates, and ZSI ran into some issues as well. So I went to Ruby and jira4r (navigator, source). Amazingly elegant, it hides all the SOAP stuff from view, producing ridiculously compact code, and so far, working flawlessly.

Martin always knew I would end up diving into Ruby

Update: check out soapUI (download).

Coincident or intentional??

When I was taking off the office, I surprisingly saw a colorful arrangement of cars in front of the building. My car is red, of course. And you see a yellow, a green and a blue car side-by-side. I believe this was just a coincident happened. I felt a little bit happy and took this picture for sharing the happiness with you.

A great president, musician, and a person who has passion

I joined in a celebration of the life of our company president, Jeffrey Walker, today. Over 200 people came to celebrate him. Because I have just joined this company a couple of months ago, I didn’t see him so much. However, I remember he helped me making our business plan and supporting me hired by this company. Actually, he is my employer.

Full of music

“Amazing Grace” sung for him.

The bands played such many nice music today.

His son made a great speech. It was pretty impressive and caused much audience to cry.

Blogs

He continued writing his blogs, radiowalker, while he fought against his cancer. The last post was written by his family. Good bye and thank you Jeffrey.

Is this usual?

One of the things surprised me was that I saw a lot of dogs in the office, when I started working in SF. I am not familiar with kinds of dogs, so I cannot tell the kinds. But I saw various kinds of dogs in the office such as Chiwawa, big strng dog, and so on. One day, I asked my colleague if this is usual office in the U.S. The answer was that we were unusual. And we are not American company, but Australian company. That’s probably answer for my questions.

He is Cooper

4 years old, good boy! He is very big, but so cute like a stuffed animal. BTW, what kind of dog he is?

It saddens me to bring the news that Jeffrey Walker aka Cancer Dude has lost his final battle against cancer. Jeffrey was my blogging inspiration and mentor. His RadioWalker blog images, humor and personal approach has greatly inspired my blog writing. In many ways he was my blogging Godfather.

Jeffrey jamming

Simon, my co-founder, and I met Jeffrey in June 2008 at The Enterprise 2.0 conference in Boston, USA. Even before then Jeffrey commented on my blog. Jeffrey warmly welcomed Simon and I to the Enterprise 2.0 community. In January 2009 when I started to loose the blogging faith and reflected on my first years blogging Jeffrey responded. He said “Be yourself. Let your personality through. Oh, and keep the images. And keep the faith, dude.”

Earlier this year when I heard Jeffrey’s cancer was back for the third time I wrote one of my favorite posts on fear, uncertainty and doubt. Within this post I refer to Jeffrey’s latest battle against cancer. Again, Jeffrey commented so nicely saying “Thanks for the kind thoughts. I really appreciate it. I am doing well.”

I did not know Jeffrey particularly well, however I consider him a friend. I found him a very kind, fun loving and passionate man. Jeffrey had a thirst for life and living. When I interviewed Jeffrey last year I saw a man who enjoyed every little experience and everything he saw. Life is so short. Jeffrey’s death is a reminder to us all on how brief our lives are and how we can live our lives. We can choose to live like Jeffrey with “zest and  passion” as his family said.

Jeffrey’s last words to me were “Live Strong”. It seems to me that Jeffrey burned so very brightly and its always better to burn brightly than fade away.

So-long Cancer Dude!!

Friends,

Last night Jeffrey passed away. As readers of his blog, you know about his zest for life. He had a passion for living and did it with reckless abandon. He gave so much of himself – to his family, to his friends, to his work – all because he loved his life and what he did.

We feel blessed to have shared his life and received his love. He has changed us in so many ways – helping us to love more deeply, be fearless and take risks. He was inspirational.

Jeffrey loved blogging and he loved reading your responses even more. He was awed by the comments people posted to his cancer blogging. He felt the love that reached out to him in every word you all wrote. Going in to his surgeries, he read the postings you wrote and it gave him strength.

Let’s give him strength again. I know that somehow, he will see your comments on this blog.

Tonight, drink a martini for Jeffrey – grey goose gibson, straight up with a twist. It’ll make him smile.

Love, Jessy, Brittany and Mac

“Guided help” – that’s when you actually do the task you need to do, and some helpful bubbles or other UI prompts tell you what to do next. You’re not reading documentation, reading help or watching a video. You’re not working on a sandbox or a test site. You are actually getting the job done and learning at the same time.

I’ve recently tried SHO Guide, a tool for creating guided help scripts. It was a lot of fun and a very worthwhile experiment.

In a nutshell, this is what happens: Using SHO Guide, you write scripts and publish them. This produces a “.sho” file for each script. Your customers then use SHO Player (freely downloadable) to play the script. It hooks into the UI of your application and guides them through the steps they need to take.

First impressions

SHO Player is a quick download (1.3 MB). Installation is painless (apart from the usual chattiness from my Windows Vista OS). SHO Guide is a longer download (60 MB).

When you get your SHO Guide licence key, username and password, you also gain access to the “Resources” part of the SHO web site. This has plenty of tutorials, FAQ, a support forum and information about training. The Quick Start tutorial is very good. Fast, with just the right amount of information to get you started. It guides you through creating a SHO script for Notepad.

Creating scripts with SHO Guide

You can record a series of steps, by clicking the “Record” button in SHO Guide and then performing the steps in the application you’re documenting. Then you can go back later to edit, insert or delete steps as required. This is very useful.

The SHO Guide authoring environment has a familiar look and feel to people who have used various types of authoring tools:

SHO for guided help

(Click the image to expand it.)

On the left of the above screenshot are the two scripts I’ve created, called “Create a space” and “View all blog posts”. Underneath the scripts are two more segments, hidden at the moment, where you can access extra step types and a library of images and other resources. In the middle is the bubble that the users will see, with various options for you to create conditional paths, filters and actions. It doesn’t take long before you know what’s what and where to find it.

The easiest way to start a script is to record it. Here’s a screenshot showing a recording in action:

SHO for guided help

In the above screenshot, I’m recording an activity on the Confluence dashboard, running in Internet Explorer. The red square shows the UI element that is currently in focus. At the bottom of the screen is the SHO Guide recorder panel, showing the key presses already recorded.  The icon of a video camera at far right means that the recording mode is active and ready for input. The icon changes to a hand when the recording is paused or busy.

Hint: It can take a while to save a recorded action. Wait until the hand changes back to a video camera before continuing with the next click or exiting from SHO Guide, otherwise your clicks may not be recorded.

The end result

Here’s a screenshot showing the starter bubble of a script I created for Confluence, helping people to create a wiki space:

SHO for guided help

The problem: You’re new to Confluence, or to another Atlassian application. You have to get something done, and you’ve no idea where to start. You’re panicking. You’re in a hurry. The UI is not helping, because it assumes at least a bit of knowledge. Atlassian, WTF??

The solution: Atlassian WTF!! The Atlassian Webapp Tutorial Fantastique.

Curious about the fairy in the bubble? She’s the Atlassian Webapp Tutorial Fairy, of course. She’s also a photograph of my earring. You can add images, videos and documents to your SHO scripts.

Here are a couple more screenshots of the same script in action:

SHO for guided help

So the user would click the “Create a space” link, as prompted by the green bubble. Confluence then opens the “Create Space” screen and SHO supplies the next bubble, prompting them to enter the space name.

SHO for guided help

In the screenshot below, see how you can present a choice of paths to the user. In this case, the “Do It For Me” option launches a set of automated steps — another cool feature of SHO.

SHO for guided help

The user also has the SHO Player toolbar, allowing them to pause or stop the script:

SHO for guided help

Want to see and read more?

Experimenting with and evaluating SHO was my Atlassian FedEx Day project. There are more screenshots in my FedEx 12 delivery note, as well as some notes about the requirements and limitations of the tool. What on earth is FedEx Day, you ask? It’s a period of 24 hours when Atlassians get to do something totally different from our normal day-to-day job, then present our findings to the rest of the company. It’s pretty cool. I wrote about it last week.

Wrapping it up

This was my first foray into guided help and into SHO. A big thank you to Matthew Ellison for mentioning SHO in his presentation on context-sensitive help at AODC 2009. (I wrote about it too.)

BTW, this was just an experiment. The scripts aren’t by any means production ready.

I haven’t had time to investigate SHO in detail. There are many possibilities, such as including sound, video and documents into your scripts, adding specific action types, trapping errors issued by the app, and so on. SHO Guide is easy to download and you can evaluate it for free for two weeks. The Transcensus guys, makers of SHO, have been very friendly and free with offers of help and discussion. Definitely worth a try. Fun too. That’s what it’s all about, huh.

I’ve just had the pleasure of reading Anne Gentle’s book, Conversation and Community, The Social Web for Documentation. I highly recommend it. The book is brim full of useful information and, even better, great ideas. This blog post is about some bits of the book that were especially interesting to me. When you read the book, you’re sure to find other sections that tickle your fancy or kick-start a killer idea

Conversation and Community by Anne Gentle

The book arrived in the middle of a busy week. My first impressions were: Yay, it found it’s way to Oz so quickly! Then I opened the package and saw the cover. You can almost taste the chocolate. Those people are all interacting with each other, great picture. What sort of keyboard is that — not QWERTY? Ah, the credits say it’s Danish. Cool.

It’s all about ‘now’

What really hits you when you read the book, is that the content is very current. It refers to blog posts written just a few weeks ago! You get the feeling that you’re engaging in a conversation with Anne and the other people she mentions, right now. You could go and comment on the blog posts and still be relevant. Awesome.

The foreword, by Andy Oram, sets the scene perfectly. Great opening: “A few years ago, this book could not have been written… A few years from now this book will be unnecessary… You are fortunate to have this book at this moment, for you can lead the next generation of information providers into the era of expert/amateur interaction.”

It’s all about ideas

Here’s a tip: When reading this book, have a notebook with you. The ideas will just keep popping into your head. For example, chapter 2 is a useful whiz-through of concepts and tools in the social web. Sprinkled throughout the chapter are some neat tips. It’s well worth a read, even if you already know most of the tools and concepts.

One idea I’d like to try, is using a Twitter feed right on the documentation pages as a way of displaying tips and FAQs. I haven’t quite figured out how to get the technology to do that for me. We need a Twitter widget for the wiki — one that shows a stream of tweets rather than just one tweet. But it’s almost possible. Then our community authors could tweet tips as they work!

Heh, this idea tickled my fancy: something to try when you’re struggling to write in a casual, simple style. Stick a picture of someone you know on your computer screen and pretend you’re explaining the concepts to them. (Page 23.)

Technical writers are in there, boots and all

Anne makes some excellent points about how our skills are transferable to the social web, particularly in integrating the social network into user assistance. (Page 25.) Key to the book is the point that readers of user assistance don’t usually care about where the information came from or who wrote it, provided it does the trick. (Page 9.) Our role includes taking this idea on board and working with the broader scope of available information.

That’s a bit daunting, but the book goes on to give guidelines on how to jump in, boots and all. Page 72 describes some participation models, and the following pages have pointers to getting involved in the social media.

How about style and standardisation? Those are endlessly debatable and particularly in the less formal online / social environment. Undaunted, Anne has written up some good guidelines. (Pages 184-8.)

Working with communities is an art unto itself

Anne encourages us to get started by listening, observing and then building up our own participation slowly, before establishing a community ourselves. Once we have a documentation community, there are ways to check the social weather in the community and keep it sunny. (Page 109.)

Anne notes that we can probably expect a small percentage of contributors, and that we should value them highly. She mentions the 90-9-1 rule: 90% reader, 9% infrequent contributor, and 1% active contributor. (Page 160.) This rings true with our own experience at Atlassian, of community contributions to the documentation. It’s interesting to see the researched statistics. And we do value our contributors, very highly. ♥

Here’s a clever metaphor cum reference to current wisdoms: “Teaching the community to fish (for information) feeds them longer than just answering questions without citing how you learned the information yourself.” (Page 137.)

Booksprints sound like so much fun, and so productive. I’d love to get involved in one. So it’s great to see some detailed advice from a book sprint diva.   The book has a long section (pages 112-124) going all the way from planning, through logistics to just plain fun.

So, did I like it?

Conversation and Community by Anne Gentle

Yes! The book is easy to read, authoritative yet friendly. That must be a hard balance to strike. Anne’s command of her subject, her wide-ranging interests and her skill with language make the book a pleasure to read. For example, I love the combined precision and pragmatism of this statement:

“This chapter contains a frozen-in-time list of some terms and tools in 2009 that are related to social media.” (Page 29.)

And the interesting perspectives on social contributions to Shakespeare’s scripts and the OED, gleaned by Anne from Alan Porter. (Page 66.)

Anne has tweeted that she’s experimenting with virtual book signings. Cool idea! I’m hoping her experiment succeeds and I’ll get a virtual signing of my copy too. Go Anne!

What other people are saying

I’ve purposefully restrained myself from reading anyone else’s review of Conversation and Community, so that I could write mine with an uninfluenced mind. Next I plan to read what everyone else has to say. A quick search reveals:

• The book’s overview page at publisher XML Press.
• Stewart Mader’s review at Future Changes.
• Jefro’s review at Jeff’s Open Source Resource.
• Various reviews at Amazon.com.
• Ellis’s review at Cherryleaf Technical Authors Blog.
• Sarah O’Keefe’s review at scriptorium Palimpsest.
• Rhonda Bracey at CyberText Newsletter.
  

Every three months or so, Atlassians go mad. The frenzy lasts 24 hours, and it’s called “FedEx Day”. Up to now, the insanity has affected predominantly the developers. This time the tech writers went bonkers too. I survived to tell the tale, just barely. Here it is.

What is FedEx Day?

Atlassian is the software-development company I work for. FedEx Day lasts from 2pm on a Thursday to 2pm the next day. In those 24 hours, you get to develop anything you like. At 3pm on Friday, the presentations start. You get 3 minutes to present your project to the rest of the company. It’s called FedEx Day because your project must be delivered overnight. The winning project is decided by vote.

It’s a pretty cool idea. You get to try something that you wouldn’t normally do in your day-to-day job. The result just may turn out useful for you, your colleagues and the company. It often does. Some FedEx projects end up as part of Confluence, JIRA or another product.

For the most part, it’s the developers who go nuts. But three FedExes ago, a technical writer won the vote for best FedEx project! That was Ed, our team lead, who wrote a Flash game called Atlassian Invaders.

How did I do?

My report is a mixed bag of nuts. The first part of my FedEx was great. It was so much fun, spending a work day experimenting with something new. I played with some cool technology and managed to get some nice results. I’ll write another blog post soon, about the project itself. Here’s a tantaliser: my project is called,

Atlassian WTF

The second part was the presentation. I was really nervous about that, right from the start. And with good cause, as it turns out. FedEx Day presentations are notorious for going wrong. Mine did. The first time I tried it, my demo stopped working each time I plugged the projector cable into the PC. Thank you FedEx gremlin!

Matt, the FedEx Day coordinator, was kind enough to let me have a 2nd attempt. I started up the demo software first, then plugged in the projector.  This worked better, but I ran into more problems later in the demo. And I turned into a wobbly jelly, something I’m apt to do. Ah well, at least I was able to demo the general idea. I needed a good stiff Coca Cola after that!

What about the other technical writers?

They were right there, in the middle of the madness. Giles converted a Confluence user macro (the {expand} macro) into a macro plugin. That’s pretty awesome. Alas, the FedEx gremlin attacked him too. His macro refused to work for his presentation. He later discovered it was because the demo machine was running Safari, while he had been testing in Firefox.

Andrew wrote a specification for automating some of our Confluence documentation release procedures. We’re hoping this will be a useful tactic in persuading a developer to write the code. We’ve offered a chocolate bribe too. Is our optimism all part of the general madness? Watch this space

Rosie started writing some sample Confluence content that non-technical evaluators can download and import into their Confluence installation. She tackled a sample intranet site and a documentation space.

Ed created a Flash game, where old-school die-hard anti-code-review developers battle it out against reviewers encroaching upon their code.

It was great to see the varied, interesting and valuable FedEx Day projects the technical writers up with. Go tech writers

The story in pictures

Friday morning, 5 and a half hours to go. Here are a few manic developers, with evidence of a hard night’s work in the foreground:

Technical writers do Atlassian FedEx Day

It finally happened. We’re going slightly mad. This FedEx Day was the first time that all the technical writers took part. Ed and Giles had done it before, but the rest of us were FedEx virgins. Here we all are, with other cross-product team members, all going just very slightly mad:

Technical writers do Atlassian FedEx Day

Half an hour left. The pace is frantic now:

Technical writers do Atlassian FedEx Day

Only too soon, the presentations start. We’re one wave short of a shipwreck:

Technical writers do Atlassian FedEx Day

We’re simply not in the pink, my dear:

Technical writers do Atlassian FedEx Day

There are more photos on Flickr. FedEx Day is fun. The presentation part of it is… nuff said. Maybe better next time. I think I’m a banana tree, and I’ll be there

Our marketing and website development teams have been working hard for the last few months, putting together a collection of videos, stories and tips about how Atlassian does agile. The result is an awesome section of the web site, called “agile@Atlassian”.

Today, the technical writer section was published, complete with videos: The Technical Writer & Agile Technical Writing. I just love the opening lines:

Technical writers are part detective and part reporter. Sleuthing through code changes, tech writers constantly sprint to assure that every feature in an iteration gets converted into instructions that any user can follow.

I think I detect Ed’s style there. Ed is our team leader. He and I are featured in the agile@Atlassian tech writing section. There are also plenty of goodies for those not fortunate enough to be technical writers, such as testers, programme managers, team leads and of course, developers.

The best bit is that these are videos of and words from work-in-the-trenches, common-or-garden Atlassians. Like me.

So yes, there’s a video of me too. It’s creepy seeing yourself on video. When I first saw it, I had to resort to some strong chocolate before regaining my usual joie de vivre.

I hope you enjoy the site! Go tech-writers@agile@Atlassian.

I stumbled across this from one of my Twitter contacts – a really interesting project being run out of the UK to collect and collate the most popular tools for learning.

UK’s Centre for Learning & Performance Technologies are seeking submissions from the education and learning community around what tools we’ve found are our favourite and/or most useful.

To my amazement as I scan the top 100 entries, Livescribe doesn’t get a mention, so clearly we need to mobilise the crowd and ensure Livescribe Pulse Smartpen makes the list – I believe it deserves to be on the list so I’m going to do my bit to make sure others nominate Livescribe

Following the instructions set down by Jane Hart this blog post serves as my submission of my top 10 tools (in no special order of importance):

1. Livescribe Pulse Smartpen 2GB
2. iPhone
3. Microsoft OneNote
4. Confluence from Atlassian
5. Facebook
6. Mzinga Social Learning Suite
7. Google Reader
8. Slideshare
9. iGoogle
10. WordPress

One thing that caught my attention was that the organiser has included informal learning – social learning. We started to really get into this space via our partners at Smart Selling and through some dialogue with luminaries like Denise Wood of Uni of SA and David Wilkins during his Mzinga days – we’ll publish some thoughts shortly on his idea of the XYZ axis of learning.

Whilst I’m not sure which of the 25 categories Livescribe would fit into – I’d really like to see the Smartpen make the list. Make sure you check out the Slideshare presentation on her site also.