Documentation—if there is one word that installs fear in most developers, it must be this one. No one in their right mind would argue the value of documentation, but it is the actual act of writing it that concerns developers so.
The secret of creating good documentation is to make the process of doing so as painless as possible, and if we are lucky maybe even attractive, to the developers. The only practical way to achieve that is to reduce friction. The last thing we need when we are in middle of fixing a bug is to wrestle with our word processor, or even worse try to find the right document to update.
What's in a name?
Throughout the rest of this article, we will refer to various URLs that point to specific areas of our Trac environment, Subversion repository, or WebDAV folders. Whenever you see servername, replace it with your own server name.
Making Documentation Easy
One of the reasons Trac works so well for managing software development is because it is browser based. Apart from our development environment, the browser, along with our email client, are the next most likely applications we are going to have installed and running on our computer. If access to our Trac environment is only a click away, it stands to reason that we are more likely to use it.
We can refer to Trac as a "wiki on steroids" because of the way the developers have integrated the typical features of a wiki throughout the whole product. However, for all the extra features and integration, at its heart Trac is basically just a wiki and this is the main reason why it so useful in helping smooth the documentation process.
A wiki is a web application that allows visitors to create and modify its content.
Let's expand on that slightly. As well as letting us view content—like a normal website—a wiki lets us create or edit the content as we desire. This could take the form of creating new content, or simply touching up the spelling on something that already exists. While the general idea with a wiki is that anyone can edit them, in practice this can lead to abuse, vandalism, or spam. The obvious solution to this is to involve people to authenticate the edit.
Do we really need this security?
Yes. Having these security requirements provides us with accountability. We will always be able to see when something is done, but by enforcing security we can see who did it. While this does cause some administrative overhead to create and maintain authentication details for anyone involved with our development projects, the benefits outweigh the costs.
Before we look at how to modify and create pages, let's see how our Trac environment looks to a normal (i.e. unauthenticated) user. To do this we need to open our web browser and enter the URL http://servername/projects/sandbox into the address bar and then press the Enter key. This will take us to the default page (which is actually called WikiStart).
When we access our project as an unauthenticated (or anonymous in Trac parlance) user, the majority of it will look and act like a normal website and the wiki in particular seems just like the usual collection of interlinked pages.
However, as soon as we authenticate ourselves to Apache (which passes that information on to Trac), it all changes.
If we click the Login link in the top right of the page now, we will be presented with our browser's usual authentication dialog box as shown in the following screenshot.
Input the proper username and password and click OK. If we enter them correctly we will be taken back to the same page, but this time there will be two differences.
Firstly, instead of the login link we will see the text logged in as followed by the username we used and a Logout link. Secondly, if we scroll to the bottom of the page there are some buttons that allow us to modify the page in various ways. Anonymous users have permission to only view wiki pages, while authenticated users have full control. We should try that out now—click the Logout link and scroll down again, and you will see that the buttons are absent.
A Touch of Style
Before we start editing the content in our wiki we should take some time to familiarize ourselves with the basics of the markup used by Trac. Since each Trac environment we create includes a copy of the Trac documentation in the wiki, this and other information is easy to find. Once we have logged back in, we need to click on the WikiFormatting link (or enter http://servername/projects/sandbox/wiki/WikiFormatting in the address bar of our browser).
The page describes the various ways in which we can format the text on our wiki pages, and contains both the markup and examples of how the text will be displayed. There is little need to repeat the whole of the page here, but we can have a look at some of the basic syntax before we move on.
Need to know basis
Instead of trying to absorb everything in one go, we will only look at the specific Trac markup when it is relevant to what we are discussing.
The most commonly used text styles are bold, italics, and underlined. We can easily use these by wrapping the text we want to modify in specific characters as follows:
- Surrounding or 'wrapping', a word with three apostrophes will mark it as bold.
- Wrapping a word with two apostrophes will mark it as italicized.
- Wrapping a word with two underscore characters will make it underlined.
These don't just apply to individual words, we can wrap any amount of text in these markers or combine them.
Another common use of styles is to signify headings and sub-headings. This is done by wrapping a sentence with equals signs. The level of the heading is derived from the number of signs that surround the text.
= This is the main heading =
This is some text.
== This is the sub-heading ==
=== This is a sub-sub-heading ===
== Another sub-heading ==
As a practical example, the title of this section as entered in a Trac wiki would be as follows:
== Formatting Text ==
The final important format is how to create links. As previously mentioned any CamelCase words will be automatically linked (for example the WikiFormatting link we clicked on the start page), as will raw URLs such as http://example.com. These types of links may be easy, but they do not look particularly nice. There is an alternative though. We can specify a link by wrapping two parts in square brackets (). The first part is the target for the link, and the second is the text that should be displayed. E.g.
[http://example.com some website]
We can also use the same format we use for linking to external sites to link pages within our wiki. We do this by using the wiki: prefix. E.g.
[wiki:SomePage some page]
Trac recognizes a variety of prefixes for linking to its different parts. As we are introduced to each part we will also learn the prefix we need to create links to it.
Preventing automatic links
Simply prefixing a CamelCased word with an exclamation mark (!) will prevent Trac from interpreting it as a wiki link. The exclamation mark will show up when editing and not while viewing the page.
It's natural that we may want to try out our new-found knowledge of the wiki formatting rules and Trac makes that easy for us as well so we need not clutter our wiki with junk. If we enter http://projects.example.com/projects/sandbox/wiki/SandBox in our browser's address bar, we will be taken to the SandBox page within the wiki for our sandbox project (yes, we are being recursive). It is now different from any other wiki page, but it helps restrict our experiments to a single location. If we are logged in we should be able to see the Edit this page button. Go ahead and click it so we can see what it looks like when we edit a page.
At the top we can see the formatting buttons that make editing a page more of a WYSIWYG (What You See Is What You Get) experience, along with a drop-down box that changes the size of the edit box. Next we have the edit box itself that contains the text and markup that makes the page we see when viewing it. Below this we have a comment box where we can provide a comment about the changes made and finally we have the buttons for submiting, previewing, or canceling our changes. We should make some changes to the contents of the page like so:
= The Sandbox =
This is just a page to practice and learn WikiFormatting.
Go ahead, edit it freely.
== My Changes ==
Wiki markup is ''so'' easy to '''use!'''
What about ThisPage?
Now if we hit the Preview button, we can see how our changes will be displayed. If we are not happy with them, we can scroll back up to our edit box and make the required changes. Now if someone else visits the page we are editing they will see the original. Only when we click the Submit changes button will the changes be stored.
Creating New Pages
If you were observant you will have noticed that our ThisPage link doesn't look like a normal link—it is gray and followed by a question mark (two actually, because we included one ourselves, but only one is part of the link). This is Trac telling us that although it recognized a wiki page, the page does not currently exist. However the link still works.
If we now click it we will be taken to an (almost) empty page with a Create this page button, which when clicked will take us to the edit view of a new page. Here, there is no difference between editing a new or an existing page.
Creating a link to a non-existent page is the easiest way to create new pages, but we can just as easily enter the name of a page in the address bar and get the same effect.
I can't find my page!
If we create a page that is not linked from any other pages, and we have forgotten what we called it we need not fear. Beneath the main Trac menu is a series of wiki-specific links. The second of these, Index by Title, will provide us with a list of all pages contained in the wiki.
Going Back in Time
Remember that we said that Trac has an internal version control system. Now we can explore to see how it works.
If we go back to the SandBox page, we should be able to see a Last Change link above the page contents. Clicking this will show us the changes made the last time the page was edited. We can see exactly what was added, removed, or modified.
We can use the Previous change or Next Change links to navigate through the history of a page, or the Page History link to view the whole history in one go.
Taking It with Us
The final feature of Trac we are going to look at here is exporting. At the bottom of every page is a Download in other formats section, with links to the formats available. For the wiki the only (current) format is plain text, which is the raw text we see when editing a page. At first glance the usefulness of this feature may not be apparent; however, there is one area that can really benefit.
Most applications ship with some sort of plain text documentation, whether it is a version history, change log, or a basic 'read me' file. We can store and edit the contents of these files within our wiki, gaining all the benefits the wiki provides but we can still save them as plain text files when it is time to release.
In this article we have seen how Trac helps reduce the friction involved in creating documentation. We discovered the basics of formatting text and looked at how to edit and create new pages.