Rockumentation

Overview

Most organizations have documentation that needs regular updates: employee manuals, privacy policies, training materials, and internal procedures. Too often those documents end up scattered across shared drives or copied into multiple places, making it harder for people to know whether they are reading the latest version.

Rockumentation keeps that content inside Rock so your team can update it in one place, manage versions when needed, and present it in a format that is easier for readers to browse.

This documentation site is itself built with Rockumentation, so you are also seeing an example of the reading experience while you learn how it works.

Viewing Books

Book and version detail screens include quick links to view content, but most readers will use the standard Books page that Rockumentation adds under the Intranet section. That page shows the books a person is allowed to view, usually in a grid or bookshelf-style layout.

Note

This page only shows published books. So if a book does not have any published versions then it will not show up, even if you have Edit access.

Tip

We use a Lava template to render this page, so you can easily customize how it looks.

Structure

Rockumentation is organized around three core concepts:

  • Books
  • Articles
  • Versions

Books

You can create as many books as you need. Each book is a self-contained set of documentation, such as an Employee Manual or a Maintenance Training guide. A book is made up of multiple articles, or pages, of content.

Tip

Books support custom attributes. You can use the Entity Attributes page to add any attributes you want.

Articles

An article is similar to a web page: it presents a specific piece of information. In an Employee Manual, for example, you might have articles like these:

  • 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. An article can have child articles, which lets Rockumentation build a tree-style table of contents and organize content like 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.

Tip

Articles also support custom attributes. You can create your article attributes when you edit the book details.

Versions

Versions are useful when documentation changes over time and readers may still need access to older material. For example, if your Employee Manual changes each year and staff still need to reference last year's policies, you can create a new version instead of replacing the existing one.

When you create a new version, you will usually start by duplicating an existing one. In an Employee Manual, for example, you might copy the 2018 version to create 2019. Because the new version is not ready yet, you can leave it unpublished until the content is complete.

You can then make changes in the 2019 version until it is ready to publish. Once published, readers will see the latest published version by default. If they need older information, they can switch back to the 2018 version. Older versions can still be updated later unless you choose to lock them.

Tip

Like books, versions can also have custom attributes attached to them.

Searching

Searching within books is supported in two different modes.

  • Built-in search: Works automatically without any extra configuration.
  • Universal Search integration: Uses Rock's search infrastructure when indexing is enabled.

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.