Image X Media

We’ve been using Basecamp from 37signals for quite awhile now for client communications and project management. We soon started to use it to store and manage our employee manual too. However, there are certainly limitations, as you can only have one level of categorization and hierarchy and you can’t change the order in which they appear.

So we decided to “port” the manual over to Drupal and write a blog post about how we did it. This post will cover how to setup a manual for both your clients and your employees using a combination of the book module and wikitools. We will also go into how to setup notifications and some other helpful related tools.

EDIT: Please note that we are currently using Drupal 5.x for our production site as we are waiting for stable releases of CCK and Views before upgrading. However, this tutorial is not dependent on either of those modules and this may very well be possible with Drupal 6.x though there may be some differences in the modules.

Step 1: Installing the Modules

You will need to make sure the following core modules are turned on:

• Book
• Comment
• Taxonomy
• Path

You will then need to download and install the following modules from drupal.org:

• Book Access (Set specific permissions per book so that clients can see the Client Support book and the Staff can only see the Staff Handbook.)
• Comment RSS (Subscribe to comments on the site via RSS)
• Default Filter (We can use this to set the default filter for certain content types and roles to be different.)
• Diff (Compare revisions)
• Freelinking (Similar to the linking syntax of Wikipedia)
• GeSHi Filter (Allows for code highlighting. NOTE: You will need to download and install the GeSHi source code. See the modules README.txt for more info.)
• HTML to Text (Required for Subscriptions)
• Mail Editor (Required for Subscriptions)
• Pathauto (If you don’t already have it, you need it anyway.)
• Table of Contents/Headings anchors (Allows us to add a Table of Contents for a given page based on the headings similar to Wikipedia)
• Talk (Puts comments for a node on a separate tab called “Talk” similar to Wikipedia)
• Textile (An all around easy to use and great text markup language, used by 37signals in Basecamp)
• Views (Not necessary for this project, but it makes it easy to make lists of nodes.)
• Wikitools (The power behind all the wiki functionality we will be using.)
• Subscriptions (This will allow staff to subscribe to specific sections of the Staff manual. It can be configured per user in very specific ways. NOTE: We only need to enable Content Subscriptions, Subscriptions, Subscriptions Mail, Subscriptions UI, Taxonomy Subscriptions)

Step 2: Setting up the Book Content Type

First, we will want to make some changes to the Book content type settings.

1. Go to admin/content/types
2. Find the type “book” in the list and click “edit” to the right.
3. You may want to rename the Book content type to something else, we called it “Manual Entry” as that best suited this scenario. You’ll probably want to change the description as well so it makes more sense for your situation.
4. Under the “Workflow” fieldset make sure that “Published” and “Create new revision” are checked and the other options are not.
5. For our needs we disabled commenting by default. For now, we don’t need clients to be able to comment on Support pages and so we will turn it on for staff handbook pages on a case by case basis. You may decide you want them on by default.
6. If you have enabled and installed the “Talk” module then there will be an additional check box that says “Display comments on separate talk page”. Make sure to check that as it will come in handy later.

Step 3: Configure pathauto settings for books

Let’s not forget to configure pathauto for books before we go and create the book pages so that we can save ourselves the trouble of updating the paths later on.

1. Go to admin/settings/pathauto
2. Under the “Node path settings” find the field “Pattern for all Manual Entry (Book) paths” (It will be named whatever you called your book content type)
3. We set this to [bookpath-raw]/[title-raw] which is the best format for a book page because the hierarchy of that page will be represented in the URL like so: “handbook/maintopic/subtopic”.

Step 4: Create the Client & Staff Manuals

Now that we have the content type configured the way we like it and the paths set up nicely, it’s time to create the actual books. You do this by creating the first page in the book and setting its parent as the top level. We’re going to create two books. One called “Support” for our clients and another called “Handbook” for our employees.

1. Go to “Create Content” > “Book” or whatever you may have renamed it to (node/add/book)
2. Type in the title of this book, in this case we’re calling it “Support”
3. Set the parent to the top level (which is the default)
4. Add in some content, I suggest adding an overview of what the book contains and how to use it.
5. Repeat this for the second book which we’ve called “Handbook”
6. In addition we’ve actually explained about how to use the Wiki features of the handbook to our staff.

Step 5: Setting Permissions

In addition to the two default roles anonymous user and authenticated user we have three roles: super (has access to everything), admin (has access to day-to-day site administration functionality), staff (see below). I’ll let you decide what roles you want to use on your site, but I would suggest that you have at least one that is similar to our “staff” role. The staff role has the following permissions checked:

• Book Module: create book pages, edit book pages, edit own book pages, outline posts in books, see printer friendly version
• Comment Module: access comments, post comments, post comments without approval
• Node Module: access content, revert revisions, view revisions
• Search Module: search content, use advance search
• Subscriptions Module: subscribe to content, subscribe to content types, subscribe to taxonomy terms

Once those permissions are set, head over to admin/content/book. You will now see the two books that you have created. Optionally, you can click on “outline” and it will show you all the pages of the book and allows you to easily edit the titles and order them. Not too exciting since we only have one page each. For now you can ignore this and click on “Access control” tab (admin/content/book/access). This new tab is provided by the “Book Access” module we installed earlier. We’ve specified that everyone can view the Support book but only admin and super can edit/delete pages. For the Handbook we’ve specified that only staff, admin, and super can view/edit the book and only admin/super can delete pages. Note that I didn’t allow staff to delete pages. This is because there is no “undo” for deleting pages and so we need to have a certain level of safety.

Now that we’ve given access to users, we need to put it somewhere they can find it. You can do this by editing the menu settings of the two book pages you created and specifying where you want them to appear.

Step 6: Setting up the Wiki Functionality

Now we have the basic book functionality setup we need to add in the wiki functionality that will help to make this more dynamic. The great thing about wikipedia is the way that it’s deeply linkable, collaborative, and constantly in flux. This meets the needs of our company manual well.

We previously installed the wikitools module, so let’s start configuring it. Suprisingly there isn’t much we need to do:

1. Go to admin/settings/wikitools
2. You have the option to specify a wiki main page, but since we are using the book module for everything I am going to set the “Wiki Path” and “Title of the main page” to nothing/blank.
3. We only need the wiki functionality for our manual so under wiki node types I will only check off “Manual Entry”
4. Under Options I have checked off the following “Node Creation”, “Node Search”, “Automatic Redirect”, “Unique Title”, “Treat underscores as spaces when looking for node titles”. You can read more about what each of these functions does exactly, right beside the check box. This is really the meat and potatoes of what wikitools does. Your settings may differ from ours of course.
5. I kept “Hijack freelinking filter” as checked because we will be using the freelinking filter for the wiki links and we want to make sure that wikitools is used when a wiki page does not exist.

NOTE: There are other wiki filter formats out there, like PEAR Wiki Filter, which allow you to use various markup languages such as MediaWiki. I chose to just use the freelinking module because our staff was already used to using the textile markup language so I didn’t want to introduce something new.

Step 7: The Wiki Input Format

Setting up wikitools alone doesn’t do much though. You really need to have an input format to see the fruit of it. I’m going to walk you through the set up of the input format that we have used. You’ve already installed the necessary modules in the first step of this article, so we can get started configuring them.

Code Highlighting (Optional)

This step is optional, and only recommended if you believe you will be including code snippets throughout your manual. Since we’re a web development company, this feature really makes sense for us.

To follow along you will need to have the “GeSHi Filter” module installed as well as the GeSHi Source Code.

1. Go to admin/settings/geshifilter
2. I’ve kept most of the geshi settings as they are by default except I have changed the following. I’ve set:
   1. “Default highlighting mode” I set to “Drupal 5”
   2. “Default line numbering” I set to “normal line numbers”

Freelinking

1. Configure the freelinking module by going to (admin/settings/freelinking)
2. See my settings below. Note that I have disabled camel case. This would turn something like MacBook or McDonalds into a link and that isn’t helpful for us. Instead only text enclosed in [[Square Brakets]] will be converted to a link.

Now that we have setup the code highlighting and freelinking we can actually create the input format.

1. Head over to admin/settings/filters
2. Create a new format. We’ve called ours “wiki-style”.
3. Make sure the new format is at least available to the staff role
4. Under filters we have checked: “GeSHi filter”, “Headings to Anchors”, “Table of Contents”, “Textile”, “URL filter”, and “freelinking filter”
5. Save the settings
6. While still on the same input format click the “Rearrange” tab. Here you can adjust the order that filters are executed. I haven’t noticed any conflicts, but you may want to keep an eye out and adjust as necessary

EDIT: In the above image I had “Line break converter” selected, however, with the textile converter this is not necessary and depending on the order they are interpreted in could even cause double line breaks.

Now that we have the input format setup, to make life easier, let’s set it so that input format is used by default when staff create a manual entry.

1. Go to admin/settings/default_filter
2. Add the following entry (Role = staff; Format = Wiki-Style; Node Type = “Manual Entry”). This will override the default and says, when a user with the role staff is editing or creating a manual entry use the wiki-style input format.
3. Add other rules as needed.

Now, let’s test out or new wiki system. I’ve included a text file which you can download, open, and copy and paste into a book page. It will give you a general idea of all the options available to you and how it works.

Download Sample Wiki Entry

Here is what that page will look like:

A couple things to note…

• You may want to learn more about the textile markup language
• Note the table of contents functionality; it will automatically add anchors to the H2 and H3 tags and produce a table of contents.
• Normal URLs are automatically parsed
• Text surrounded with [[Square Brackets]] are made into wiki links. Try clicking on one.

Step 8: Managing Revisions

Earlier on in this process, I got you to set revisions on by default. We’re going to take advantage of this now. Go ahead and make a change to an existing page and add a log message. When you do this the revisions tab will appear. Because we installed the diff module earlier we will get an added bonus when we click on the revisions tab.

You can now choose two different revisions and then click “Show diff” which is short for “Show differences”. When we do that we are shown the changes that were made.

Step 9: Discussions

So we’ve setup two books to be used as our client and employee manuals and we’ve add the wiki functionality to make this a more collaborative effort. However, from time to time we need to discuss company policies or best practices. We’ve already installed and configured the talk modules so let’s go ahead an enable it for this message.

Edit the book page you just created and under “Comment settings” set it to “Read/Write” and save. Notice that right away a talk tab is added. If you click on that you can now post the first comment.

Step 10: Staying up to date

It’s no use having a manual if no one reads it. Initially, we thought we might be able to keep people up to date via RSS. One could easily install the Views module and create an RSS feed and in addition install the Comment RSS module to include comments. However, that doesn’t allow for people to only get notified about the topics that matter to them and it doesn’t ensure that all changes to manual entries that affect them run past their eyes. So we decided to the use the subscription module.

1. Upon installing the Subscription module you will want to make sure Content Subscriptions, Subscriptions, Subscriptions Mail, Subscriptions UI, and Taxonomy Subscriptions have been installed. In addition you will need to install “Mail Editor” and “HTML to Text”.
2. Create a new vocabulary called Departments. (admin/content/taxonomy)
3. Set it to show up for “Manual Entry” or “Book” (whatever yours is called)
4. And allow “Multiple select”
5. Next add the terms that you would like to use for example: Contractors, Design, Development, Employees, Information Architecture, Sales
6. Go to admin/settings/subscriptions
7. I set the unlisted content types and blocked content types to all but the manual entry (book) content type.
8. I set all the vocabularies to “restricted” and “omitted” except for “Department”
9. Under user defaults you can set the defaults for new users, I added the following to the defaults:

NOTE: I haven’t added any default subscriptions to specific user roles. You may want to.

Conclusion

That’s it. We’ve created a corporate manual that we can use for documenting client support as well as for internal employees. We’ve used the book module so that we have the ease and strucuture it provides, but we’ve also used wiki and revisions tools to allow for a collaborative. And in the last few steps we’ve enabled subscriptions so staff members can stay up to date on policies that matter to them.