FogBugz includes a wiki for creating and maintaining documentation.
The FogBugz wiki is a useful tool for creating and maintaining documentation. A wiki is a collection of related articles. For example, you might have one wiki called “Employee Handbook” with separate articles for your vacation policy, expense policy, and parental leave policies. You might devote a separate wiki to internal documentation about your product, with one article for your deployment process, one article outlining your system architecture, and one outlining your product’s guiding principles. You can use the wiki for any team documentation: specifications, requirements documents, knowledge base articles, status reports, internal technical documentation, and external end-user documentation. Because anyone can edit any article, the quality of each article will improve over time.
Each wiki every article can be edited by anybody (or you can more narrowly define your permissions), and a complete record of all edits is maintained forever. This allows anyone with a little bit more information to improve an article simply by clicking the “Edit” link and editing it in place.
You can create as many wikis as you need in your FogBugz account.
- Each wiki has a home page accessible from the Wiki menu; it can link to an unlimited number of other articles.
- You can create one or more templates, which specify the design of each wiki page. All pages from the same wiki must use the same template.
- Each wiki has its own set of permissions. You can make some wikis open to the public, while others are more restricted.
Creating a New Wiki
To create a new wiki, visit Wiki > Manage Wikis, then click “New Wiki”. You’ll see an editor for your Wiki’s root article, which should generally be an overview that introduces the entire wiki.
Creating a New Wiki Article
There are a few ways to create a new wiki article. First, you can click “New Article” from the wiki menu to the left of any wiki. One of the advantages of a wiki is that links between wiki articles help to communicate about interconnected topics, so we’ve also made it possible to create a new wiki while you are editing an existing article. Simply click where you want a hyperlink to the new article, and choose Insert | New Article. This makes a link to the new, initially-blank article right in the current document. The link will be red to remind you that the new article has not been written yet. Save your changes and click on the red link to get to the new article.
Editing a Wiki Article
In general, when you want to insert a link:
- Type the text that the link should have, and select it
- Choose Insert | Link
- Enter the destination that the link should go to.
The wiki is tightly integrated with FogBugz. You can create a link to any FogBugz case simply by typing the case number when you insert a link. This becomes a bidirectional link; the FogBugz case will link back to the wiki article automatically. Likewise, you can link from a case to a wiki page by typing ‘w’ and the article number when editing the case, for example W123.
You can also attach a file to a wiki article and create a link to it in one step by clicking Insert | Attachment…
Images and tables
Add images to your document by choosing Insert | Picture… The image will be stored in the wiki and embedded in the page. You can resize the image in Firefox (only) by clicking it and dragging the corners or edges. Set a title and formatting by right-clicking and choosing Picture Properties…
To create a table, choose Insert | Table… and set the options. You can add and remove columns and rows and split or merge cells by right-clicking the table.
Insert an automatically-updating tables of contents for an article with the Wiki Table of Contents plugin.
FogBugz does not automatically maintain a table of contents to all wiki articles. If you delete the last link to a given article, even though it still exists in FogBugz, you can only get to it by directly typing the URL. This is called an orphaned article; administrators can see a list of them in the wiki configuration page. To delete an article, remove all links to it (see the article’s Info page for a list) and then delete it from the orphaned articles list.
If you want to change the fonts, styles, and colors used in your articles, just select a new template. To do so, choose Wiki | Manage Wikis… to navigate to the Wikis page, then click the Configure icon next to your wiki’s entry in the list. This will take you to the Edit Wiki page, where you can select a template.
To edit an existing template, click on the Customize Templates link at the bottom the Wikis page. On the Templates page, click the Configure icon next to a template’s entry in the list. The Edit Template page will allow you to customize page layout HTML, view a set of template variables that you can embed in your wiki (for example, the “$incoming_links$” variable lists all pages that link to the current page), edit the wiki’s CSS stylesheet, and specify a set of image (or other content type) attachments for use in your layout HTML. The default FogBugz 8 template includes quite a few features via these placeholders. Details here.
The FogBugz wiki is completely multiuser; any number of users can edit each article simultaneously without clobbering each other. FogBugz will detect if two users’ changes conflict, and ask the second user to decide how to resolve the conflict. If two users edit different parts of a document, their changes will not conflict and will both be saved.
FogBugz automatically saves drafts in the background as you are editing, in case you close your web browser or it crashes before you can save. When edit the article again, you’ll be given a chance to recover your changes, even if you never clicked Save.
Each wiki can have its own set of granular permissions. You can choose whether Anonymous and Community users can see and edit the wiki, and you can enable finer controls by setting assigning the wiki to a group.
Wiki article information
(FogBugz For Your Server customers: make sure the three Wiki Article Info plugins are enabled)
When viewing of editing a wiki article, there is an Info link next to Edit at the top-right. The wiki article info page contains article details, history and a list of all links to and from the article.
The wiki history browser (“recent changes”) shows a list of each change made to the article over time, who made it and how much of the content was changed. For each version, you can click a link to see a graphical display showing what changed relative to the previous version. You can compare any two versions by clicking Next and Previous for each side of the comparison until you see the two versions you want. From the article editor, you can go back to any old version by clicking the left arrow next to the date and time in the top-right, then click Restore Old Version in the top-left.
If somebody has made a change that you don’t like, just restore the version before they made the change and save it as the current version. This has the effect of undoing their change in two clicks. In practice, this means that it’s easier to clean up vandalism than to vandalize in the first place, and it has the effect of keeping the quality of a wiki article very high even when you allow anyone in the world to edit it.
The info page also shows you what links to the article and what outbound links the article contains. You can copy the article to a new one, set it as the root for the containing wiki or delete the article. You can only delete a wiki article when no other articles link to it (making it an “orphan”).
Users can subscribe to a wiki article to receive notification when it changes. This is useful to track projects or interesting documents, and it also makes it difficult for a vandal to deface a page without anyone noticing. Vandals eventually give up when they realize that they’re not getting anywhere and move on to something else, like throwing stones at rabbits.
Searching wiki articles
FogBugz search includes wiki articles. To search only wiki articles, add type:wiki to the search terms. To quickly search just the current wiki, use the search box on the article page (if included in the current template).
Tags make it easy to find what you are looking for in FogBugz. Add tags to wiki articles in the tags field at the bottom of the editor. Find your tagged articles later by searching for type:wiki tag:my_tag