Reviewing wiki documentation via Crucible

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.