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!
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.
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.
We use a Lava template to render this page, so you can easily customize how it looks.
The Rockumentation system is divided into multiple stages.
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.
Books support custom attributes. You can use the Entity Attributes page to add any attributes you want.
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:
- Vacation & Sick-leave
... 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
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
Articles also support custom attributes. You can create your article attributes when you edit the book details.
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
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.
Like books, versions can also have custom attributes attached to them.
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
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