ffeathers — a technical writer’s blog

Jamie Oliver’s reason for choosing the title “The Naked Chef” was that it implied simplicity. He wanted to convey the idea that simple recipes are best. Simplicity is something we technical writers strive for too. In choosing vocabulary and syntax for our technical documentation, we’re at least consistently good at dressing down, even if we don’t often go the full monty. So I think we can justifiably claim the sobriquet, “The Naked Tech Writer”

You may remember my agile turtle, original and then re-engineered by Ryan. Here she is again, naked as the day she was drawn:

By Ryan

Tom Johnson has the topic of simplicity well covered. So I thought I’d look into the other possible interpretations of our new nickname, The Naked Tech Writer.

Out there on a wiki

“Naked” might mean “out in the open, for all to see”. If you are writing documentation on a public wiki, as I am, this rings very true.

“Every change you make, every page you break, they’ll be watching you.”

Readers add comments to the documentation pages, and they get to know you by the replies you give. We try to respond to most people’s comments. If necessary, we also update the documentation in response to their requests. Some time later, we remove the comments and our replies.

So while the documentation itself remains unadorned, devoid of personal style (as much as possible), the comments on the pages often do reflect the character of the technical writer. It can be rewarding to converse with your readers like this. Sometimes it’s just plain fun.

Here’s an example of a recent chain of comments on a page in the Confluence documentation. By the time you read this blog post, the comments may have disappeared, so I have taken some screenshots:

The Naked Tech Writer

The conversation got better and better. Here’s another screenshot, with the comments shrunk to show just the first few words of each:

The Naked Tech Writer

When was the last time you had that much fun with your clothes on?

Baring all in a blog

Quite a few technical writers are keen bloggers. Perhaps it gives us a chance to reveal the more showy side of ourselves. “You see, technical writers do have dress sense after all.” It’s difficult to make documentation look sexy, though some people do manage. But you can dress your blog to the nines.

Dispelling the myth via a photo album

Technical writers are coming out all over the show. Have you seen the photo gallery published by Cherryleaf? “I’m a Technical Writer — Dispelling the Myth”. My team is on page 13. Are you in there too?

I’d be sorry to go back under cover

Sometimes people email me directly, such as when their question relates specifically to their own environment or when it’s “big” question about processes and procedures, rather than something which relates to a specific page of the documentation.

I enjoy this kind of direct contact with the readers. Their comments enrich the documentation. Often I need to go and do some extra research to find the answer to a question. That makes it even more rewarding when I can give the person the answer, and of course update the documentation if necessary.

There are a couple of things on the downside of having such a visible profile. It’s time-consuming, responding to comments on the documentation pages and answering emails personally. At first it was even a bit disconcerting to receive direct emails. But right from the very beginning, even in the first few days of starting work on the wiki, I loved it.

A while ago I received an email from Shirley, who was watching the entire Atlassian Confluence documentation wiki. Such dedication! One day she noticed a large number of page-changes flash past her RSS feed, all with the same time stamp. It looked as if I had changed many pages all at the same time, and she wanted to know what the magic was. She ended her email with:

“And I hope this provides you with a good laugh!”

I explained that I had changed a page name and Confluence had automatically updated all the hyperlinks from other pages throughout the wiki.

And it did give us both a good laugh.

If I ever go back to a less “naked” form of technical writing, I will miss the exposure the wiki gives.

Other ways of undressing

The Naked Tech Writer is here, and here to stay. I’m sure there’s a lot more fun to be had with this nickname. Let me know if you think of any other ways a technical writer gets nekkid. And thank you in advance to WordPress and Akismet for the reams of spam they will undoubtedly trap on this blog post!

I have been playing around with Crucible, Atlassian’s peer code review tool. The latest version of Crucible allows you to review Confluence wiki pages. This is a new feature, so I decided to try it out. Also, I was wondering why you might want to use an independent tool to review a wiki page, when you could instead just add comments to the page or update the page directly.

So, my question is, why would you want to use an independent tool to review a wiki page? I guess an advantage is that you and your team can review the Confluence document without changing the content of the page. You can add line-by-line comments and conduct a full review workflow via the Crucible web interface. Also, people who don’t have permission to update the Confluence site can still participate in the review.

Even so, a wiki hugger like me finds it an odd idea to move outside the wiki to do the reviews. It would be interesting to hear other people’s opinions. If you have tried Crucible for wiki reviews, let me know what you think. Perhaps you’re a Crucible hugger

And just in case you’d like to try out Confluence-Crucible integration now, here are the steps I followed to set it all up.

Setting up Confluence and Crucible

I decided to go the simplest route and have a standalone version of Confluence and a standalone version of Crucible, both running on my PC with their own independent web servers. I’m running Windows Vista, Confluence 2.10 and Crucible 1.6.5a.

Here are the steps I followed:

1. Download Confluence from the Atlassian download centre.
2. Install Confluence by unzipping the downloaded file, then run the setup wizard, as described in the documentation. Leave the port as the default 8080, and the base URL as the default “localhost”.
3. Download Crucible from the Atlassian download centre.
4. Install Crucible by unzipping the downloaded file, as described in the documentation. Leave the port as the default 8060, and the base URL as the default “localhost”.
5. Make sure both your Confluence and your Crucible servers are up and running.
6. Access Confluence in your web browser by going to http://localhost:8080. Log in using the administrator account you set up during installation. Go to the Confluence Administration Console, by selecting “Confluence Admin” from the “Browse” menu.
7. Access Crucible in your web browser by going to http://localhost:8060.
8. In Confluence, install the Crucible plugin. I installed the plugin manually: first download the JAR from the location shown on the plugin page; save the JAR onto your hard drive; then upload it into Confluence via the “Plugins” page in the Confluence Administration Console. See the documentation.
   
9. Configure Crucible to recognise your local Confluence instance (http://localhost:8080) as a source repository. To do this, click the “Administration” link at the bottom of the Crucible screen. Then select the “Repository List” in the Admin Menu. Then click “Configure Plugin” under “Repository Plugin: Confluence”. I did not restrict the setting to a specific space.
   
10. Now you need to tell Crucible that Confluence can be trusted. In the Crucible Admin Menu, click “Trusted Applications” then “Add a Trusted Application”. Enter the URL of your Confluence site (http://localhost:8080) and then click “Get ID”. There’s no need to enter anything else on this screen. Then click “Save”.
    
11. You also need to tell Confluence that it can trust Crucible. In the Confluence Administration Console, select “Trusted Applications”. Enter the URL of your Crucible instance (http://localhost:8060) and click “Send Request”. There’s no need to supply any additional IP address or URL path.
    
12. Set up a couple of usernames in Crucible and Confluence. To do a full review workflow, it’s useful to have a few different usernames. Then one person can kick off the review and ask a couple of others to participate. Here’s a useful tip: Your usernames need to be the same in Crucible and Confluence. I added users called “arthur”, “trillian” and “zaphod”. In Crucible, select “Users” from the Admin Menu and add your usernames. In Confluence, select “Manage Users” from the Administration Console and add your usernames.

Reviewing some wiki documents

Now Confluence and Crucible were talking to each other. Next I needed a set of documents in Confluence, so that I could get my users to review them. Then I could set up the reviews in Crucible.

1. In Confluence, create the set of documents that you want reviewed.
   Tip: I downloaded a ready-made documentation set. I used the Crowd documentation, because it’s a reasonable size. Download the XML zip file from the Atlassian documentation site and then import it into your Confluence instance as described in the documentation. This will create a whole new space called “CROWD” with a number of documentation pages.
2. In Confluence, make sure your users have at least view access to the space where your documents are held. This will be true if you have not changed the defaults, because by default all members of group “confluence-users” will have viewing rights to your space, and all users are members of that group.
3. Now log in to Crucible as one of your users. I chose Trillian.
4. Go to the Crucible home page (localhost:8060) and then click “My Crucible Dashboard”.
   
   
5. Click “Create New Review” at the top right of the screen.
6. Enter review title, select the reviewers (I ticked Arthur and Zaphod) and describe the objectives of the review.
   
   
7. Now you can choose the files (wiki pages) that you want reviewed. Scroll down the Crucible review page, until you see the “Review” and “Manage Files” tabs.
8. Click the “Manage Files” tab.
9. Next to “Repository”, select your Confluence site from the dropdown list.
   
10. Within the “Manage Files” tab you’ll see some subtabs: “Changesets”, “Files”, “Patch” and “Upload”. Click the “Files” tab.
11. Now you’ll see a tree view of your Confluence site. My tree view shows my “CROWD” documentation space and the “ds” demonstration space that came with my Confluence installation. Click the pointy arrows next to your documentation space, to open the tree until you find the pages you want to review.
12. Click a page name. A list of its child pages will appear on the right, where you can select one or more for inclusion into your review.
    
13. Select as many pages as you like. Above, I’ve just selected the page called “Installing Crowd”. When you’ve finished, go back to the “Review” tab to see the pages you have included in the review.
14. Click the “Start Review” button. Crucible will now send an email message to the people you selected as reviewers, letting them know that you’d like them to participate in the review.
15. If you like, you could now log Trillian out of Crucible, and log in again as Zaphod. Then go back to “My Crucible Dashboard”. Zaphod’s dashboard will show the review that Trillian created.
    
16. Click the review number (CR-11 on my screen above) to open the review.
17. Because Zaphod is not the creator of the review, he cannot add or remove files from the review. But he can click “Add a new general comment” to say something about the review as a whole (like “I am Zaphod” or perhaps something slightly more relevant).
18. He can also click the arrow next to a page name to see the wiki page content, which is displayed in Wiki Markup mode. He can choose to see the entire page content, or just the most recent changes (the “diff”).
    
19. And he can click a line to add a comment about that line (like “Zaphod was here” — this is Zaphod we’re impersonating, after all; other people might actually make a useful comment on the content of the wiki page).
    
20. Crucible uses colour-coding to identify reviewers and to highlight recently-modified content in the wiki page. In my screen below, Zaphod’s comments are highlighted in light blue. The unmodified page content is in black text. And the recently-added page content is highlighted in green.
    

Next, you could log in as Trillian or Arthur, and reply to Zaphod’s comments or add more comments on other wiki lines. Trillian and Arthur’s comments will be in different colours.

I haven’t illustrated the whole Crucible workflow, because this blog post would get very very long. Basically, Zaphod and Arthur will add their review comments and then mark their reviews as complete. Trillian will receive notification that they have finished, and she can decide to close off the review when all is said and done.

How’s the stamina?

There’s a lot more to Crucible that I haven’t put through its paces yet. And of course, you can use Crucible to review documentation that’s not on a wiki. If your documentation is held as XML, for example, in a source control repository, then that’s what Crucible is designed for.

Naturally, there is some Crucible documentation

Let me know how it goes

If you do try this out, I’d be very interested to hear your ideas and opinions. And if you have any requests for the Crucible or Confluence teams — feature requests, bug reports, praise… — try raising a request in the Crucible or Confluence projects.

Earlier this week I hosted a webinar on using a Confluence wiki for technical documentation. The guest speaker was Jon Hertzig, a technical writer at OpenCloud. He showed us his Confluence documentation site and talked about his use of plugins and macros in addition to core Confluence functionality.

We recorded the webinar session, and you can now view it on the Atlassian blog.

This was a very interesting experience for me. It’s the first time I have conducted a webinar session, and the first time I’ve been bottled up and served as a voice-over on the web.

I’d like to say a big thank you to Jon Hertzig, who did a great job of showing us his Confluence documentation site. And thank you to Morgan and Jon at Atlassian too, for suggesting that I host the session. It was fun, although a bit nerve-wracking at first. By the time we got to the question-and-answer session, I was thoroughly enjoying it.

Thank you also to all the people who attended, and for your contributions to what Morgan calls the “killer Q & A session”

Next week I’ll be hosting a webinar (an online web conference) on using a Confluence wiki for technical documentation. The guest speaker is Jon Hertzig, a technical writer at OpenCloud. Jon and the OpenCloud team have done an awesome job of creating wiki documents and tailoring their Confluence site to meet their requirements. Join the webinar if you’d like to ask him all about it

OpenCloud’s documentation portal is hosted on Confluence. You can see what they’ve done by going to the OpenCloud Development Portal or directly to the OpenCloud Rhino product documentation.

Using a wiki for technical documentation is interesting. It requires a technical writer with a certain stalwart enthusiasm Jon and I had a short meeting last week in Sydney. I’m impressed by his obvious enjoyment of the work and by the great job he’s done,

• investigating the capabilities of various tools
• deciding on a wiki
• choosing Confluence
• converting a large documentation set to Confluence format
• and then making use of Confluence macros and plugins to build an appealing, functional and useful documentation wiki.

Join us in the webinar?

Jon will give a half-hour presentation and then we’ll be able to quiz him about how he did it, what the differences are in using a wiki instead of other media for technical documentation, and what the advantages and pitfalls may be.

Date/time of the webinar session — there’s just one:

• If you’re in the USA sort of time zone: Wednesday 14th January at 3pm PST.
• If you’re in Australia or surrounds: Thursday 15th January at 10am AEST.

Follow this link if you’d like to register for the webinar:

https://www2.gotomeeting.com/register/164766165

It will be fun to “see” you there!