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.
    Reviewing wiki documents via Crucible
  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.
    Reviewing wiki documents via Crucible
  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”.
    Reviewing wiki documents via Crucible
  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.
    Reviewing wiki documents via Crucible
  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”.
    Reviewing wiki documents via Crucible
  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.
    Review wiki documents via Crucible
  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.
    Reviewing wiki documentation via Crucible
  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.
    Reviewing wiki documentation via Crucible
  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.
    Reviewing wiki documentation via Crucible

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.

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 17 January 2009, in atlassian, Confluence, technical writing, wiki and tagged , , , , , , , , , , . Bookmark the permalink. 13 Comments.

  1. What a great Idea! I was giving someone a demo of Crucible the other day, and they asked me if they could do word document reviews using Crucible – they liked the ajax-style commenting and discussion over some bit of text.

    This could work, all I have to do is import the word doc into Confluence.. Thanks for the idea!

  2. Hallo Sherif
    And thank you. I hadn’t thought of the Microsoft Word aspect. Yes, you can use the Confluence Office Connector to import a Word document into Confluence, then do the review with Crucible. Great idea! Let me know how it works out.

  3. Laurent Noyelle

    Very interresting article, thank you very much.

    This article raise the following question : if you decide to manage the document in confluence instead of having files (Excel, Word, PowerPoint, …) in order to use Crucible to review them, how do you manage the confluence content in terms of Configuration management process ?

    To be more precise, when your documents consist of files, you can upload them in a CM tool and tag / baseline a dedicated version of the documents with the linked source code files. How do you tag / baseline the content of confluence ?

    Cheers

  4. Hallo Laurent

    That’s a good question🙂 We use a different mechanism for version control and release management, because our documentation is entirely on the wiki. So, as you’ve pointed out, tagging the content in a SCM for a particular software release is not possible.

    We use Confluence spaces as our version-control mechanism. For each major release of each product, we create a snapshot of the documentation and archive it to a new space. I’ve written it up in another blog post. Also, I gave a presentation at WritersUA 2009 last week. The slides and notes are available on this blog post. Part of that presentation is about release management.

    I hope that helps!
    Cheers
    Sarah

  5. I started using this solution with our installation of Confluence and Crucible. A few items I discovered which need mentioning. I am using Confluence 3.0 and Crucible 2.03. I had to turn on the Remote API on Confluence – it was off by default.

    Other than that it seems to work 99% of the way. Can you find out if the developers are working on this?

    There are a few items that could use improving.

    (https://developer.atlassian.com/jira/browse/CONFCRUPLUG).

  6. I’d really like to be able to use this capability, but the plugin doesn’t appear to work with Confluence 3.5.7; at least, I am getting “Repository not available” when trying to set reviews up using it. Is there any hope of reviving it? It would seem like something that should be in the bundled plugins at this point.

  7. So this won’t work with Confluence 4.x? I saw a demo of code review with Crucible, the inline threaded comments in a transcluded page would really be great for discussing changes to Confluence-based documentation.

  1. Pingback:   Weekly links roundup by Communications from DMN

  2. Pingback: Advice on writing a poem relating the Puritans to the Crucible? :Write Better!

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: