Overview

We all have documentation that we need to keep up to date. Employee manuals, privacy policies, new employee training materials. Usually we put these in Word files that are littered all over your network server. Users never know if they are looking at the most up to date version. Sometimes you might even put the current version of these into Rock. That helps but then you need to remember to update these files in Rock whenever you update the master document.

Wouldn't it be better if you just wrote the information in Rock and kept it up to date there? If you do have specific forms and PDFs that users might need to download and fill out you can even upload those and attach them to your articles.

Oh, and if you were wondering what Rockumentation looks like, you're looking at it now!

Viewing Books

While the detail pages of Books and Versions does have a quick link to take you to the page for viewing that book or version, there is a more standard way your users will use. When you install the plugin a new page also gets created in the Intranet section. This page, called Books, will show a list of all books the user has access to see and displays them in a sort of grid or bookshelf layout.

Structure

The Rockumentation system is divided into multiple stages.

• Books
• Articles
• Versions

Books

You can create as many books as you wish. Each book should be thought as a self-contained source of documentation. So you might have a Employee Manual book in addition to a Maintenance Training book. Each book would be made up of multiple articles, or pages, of content.

Articles

An article can be thought of as a web page. It displays a specific set of information. In our example of an Employee Manual we might have the following (and more) articles:

• Benefits
• Vacation & Sick-leave
• Holidays

... and so on. You can link one article to another. For example, your Benefits article might talk briefly about the holiday system in use but then link them to the Holidays article to get more specific information about what holidays are observed.

Articles also have a hierarchy to them. An article can have child articles and will end up displayed in a tree-style table of contents. This allows you to group your articles into a format fitting for an online book.

While not required, it is recommended that each article be kept fairly short. We would recommend the reading time be kept to under 10 minutes per article. Keeping your articles short will force you to divide them up into multiple articles which then makes it easier for your users to find different information in the table of contents. It also makes for a less daunting task when they need to read an article rather than having to sift through looking for the specific information they want.

Versions

Previously, we mentioned that you often have multiple versions of your training materials. Usually this is due to things like dental plans changing or other things like that. Sometimes you want to keep previous versions around for users to read, other times you just want to edit in place and not care about the previous content. The choice is up to you. If you update your Employee Manual each year with all the changes that have been made and want to allow your users to view the past information still, you can create a new version.

When you create a new version you usually start by duplicating an existing version. In our Employee Manual illustration, you might have a 2018 version of the manual. At the end of the year you would want to start working on the 2019 version so you would then make a copy of the existing 2018 version and title the version 2019. Since it's not ready yet there is a flag on each version that allows you to mark if that version should be published or not.

At that point you can start making all your edits to the 2019 version and then once you are happy and think everything is ready you could mark it as published. Once you do that then when people go to view your book they will be shown the latest published version automatically. If they decide they want to see what it was like in the 2018 version they can switch which version they are looking at. If you need to you can still go back and make changes to the 2018 version as well.

Searching

Searching within books is supported in two different modes.

By default an internal sub-string search is performed with a little bit of logic to try and push more relevant articles to the top of the results. This requires no configuration on your part and happens automatically.

However, if you are using Universal Search, then you can enable the indexing component and the search feature will switch over to using Universal Search for its search logic. The UI will remain the same, but behind the scenes it will use Universal Search.

When you enable Universal Search indexing you can also build your own custom search pages. However, be aware that when displaying search results this way only results from the currently published version will be available.