New Documentation Portal

In the past years, we have invested heavily in our product documentation. The latest result is a new documentation portal that provides access to any article or document that we have on uberAgent.

What’s in the Documentation?

The list of articles hosted in the uberAgent documentation is quite extensive. In addition to obvious installation guides and the such, we have a comprehensive list of all the metrics collected by uberAgent, a knowledge base, as well as a list of practice guides – articles that explain how to solve real-world problems with uberAgent.

vlDocs

When we started planning a modern approach to documentation, we quickly realized that we wanted a system that would support versioning the docs in the same way we version our software, including the ability for customers to switch the docs to the version they have in use. We found inspiration in Splunk’s Ponydocs, a system based on MediaWiki, and looked for a comparable solution for our WordPress site. To our astonishment, nothing of the kind existed. There were simply no decent software product documentation plugins on the market. So we built our own, vlDocs.

Just like Ponydocs, vlDocs has inheritance built-in. If you write an installation guide for your product’s version 1.0, the content of that page is probably not going to change very much when you release 1.1 or 1.2, if at all. That is where inheritance kicks in. In vlDocs, a new version inherits all documents from its parent version by default. You only need to touch the documentation when you actually change how the product works.

If, for example, you change how a feature works in version 2.0 of your product, you branch that feature’s documentation page at version 2.0 of the documentation, and edit the branched copy to reflect the changes in the product. The documentation for later product versions will inherit not from the original, but from the branched page instead.

vlDocs 2.0

Ease of use and quick access to information are of paramount importance for a documentation solution. In this latest version 2.0 of vlDocs, we added several features that improve the overall user experience.

Documentation Portal

The new documentation portal serves as entry point and combines search functionality with quick links to the most important topics and chapters.

Search

Search is available on the portal as well as on every individual documentation page – just look for the magnifier glass symbol in the upper right corner:

By default, a search covers the latest version of all chapters of all products. Optionally, searches can be restricted to individual products or chapters, or specific versions of a product.

Table of Contents

If the screen is wide enough, a table of contents is displayed on the left-hand side. On smaller screens, the table of contents is accessible through a hamburger menu.

Keyboard Navigation

When you open the documentation portal, the keyboard focus is already on the search field and you can start typing your query right away. Search results are fetched dynamically while you type. Navigate the results with the cursor up/down keys and press ENTER to bring up the page you are interested in.

On individual documentation pages, the search overlay can be accessed by typing / (forward slash). Press ESC if you want to get rid of the search overlay.

Breadcrumbs

Every documentation page now has breadcrumbs above the page’s title that allow for yet another type of navigation.

Full-Width Display

The metrics documentation has some tables that can use every pixel of screen real estate. Documentation pages now provide that space by using the available width.