Search This Blog


Monday, November 19, 2007

FogBugz-- wiki

Continuing on the posts on FogBugz review, today I am going to talk about one of the new features in FogBugz, Wiki.

Wiki, according to the Wikipedia, is a website that allows users to add, edit or delete items collectively. It is a very important feature because it allows one to track the specifications, and the corresponding requests and bug cases together, all in a common place.

The biggest problem we had have, prior to FogBugz 6, was that we were not able to keep track of our specs. These specs were composed in Microsoft Word, and so, they were stored scattered in different computers, often at dark corners where everyone would tend to overlook. There was a danger of losing these documents whenever a staff quited, or formatted his computer, or simply forgotten that he had written about them. Not just that, since spec documents were especially hard to maintain, they were often remained frozen in the ice even though the formal specs ( that is, the code) had undergo major revisions. In other words, the specifications were only useful at the initial stage of the development, at most.

So when the technical writers needed to write the help files, he would have to consult the horse mouth ( that is, the developers) to get accurate information. And the developers in turn, would have to consult their code before they could say anything. No one would go and read the initial specifications. They were there for historical interest.

Thus there is little wonder why most of the members on our team wanted a Wiki. A Wiki style document editor inside FogBugz is advantageous compared to a non-Wiki tools in at least the following ways:
  1. It is collaborative in nature. In other words, everyone can edit it. Other people can always take over a document when the original authors stop maintaining it
  2. It can be easily retrieved. A Wiki in web apps centralizes all the documents. To find anything you want you just have to do a search
  3. It is highly visible. When you see FogBugz, you see the Wiki workspace automatically. Hence people have a higher inclination to update it.
Despite the apparent benefits of FogBugz Wiki, we do have some problems with it. Here are a few of them:
  1. There is no one-click process that will automatically transfer and transform the MS documents into Wikis. This feature would be useful for those who write a lot of specs in the MS and now want to transfer them to FogBugz.
  2. FogBugz cannot compile to any other formats. This means that for help file, one needs to manually transfer the work from FogBugz to another help compiler. Multiple maintenance effort, so troublesome!
  3. No autosave. OK, this maybe very trivial, but having used to Google Docs makes me miss the autosave feature very much.*
  4. Cannot view the HTML source. Not a common feature, but would be useful because who knows one day someone may need to mess with the HTML thing manually.
  5. Missing Print function in edit mode.
  6. Tagging, or labels are missing as well. When you have a very large collection of documents, you will miss the tagging feature a lot.
  7. The templates for Wikis are hard to use. You need to know a bunch of HTML coding to make it. No drag-and-drop. Sorry.
But still, I still consider FogBugz to be a valuable bug tracker and a specification editor. It allows us to link between issues and the specification. This, itself, is already worthing more than other similar but unintegrated applications combined.

*FogBugz Wiki does have Autosave. Thanks Joel Spolsky for pointing this out.


Rob said...

Not just that, since spec documents were especially hard to maintain, they were often remained frozen in the ice even though the formal specs ( that is, the code) had undergo major revisions.

My team uses a Wiki (not the FogBugz one) to record our design decisions too; turns out the reason the "real" design (the code) doesn't reflect the official design (the documents) is not because MS Word docs are hard to maintain ;-]

What's the answer? Not sure. You could try having the help file guys just read the code instead of asking a developer. (What's the emoticon for tounge-in-cheek?)

Meanwhile, expect your weekly status meeting, daily scrum or whatever to contain the regular exhortation to "make sure you update the Wiki".

Soon Hui said...

Thank you for sharing your experience with me. While Wiki documentation alone may not be sufficient to guarantee updated specs, but without Wiki, there is literally no hope one could have updated specs.

I am not sure how tightly integrated your Wiki and issue tracker are. But if they are presented side-by-side, people have more chances to read ( and hence maintain) the wiki.

Just my 2cent.

Anonymous said...

You can view the wiki HTML source through wthe FB API.