Review of Paligo

Paligo is a web-based authoring tool and component content management system for creating technical documentation. Unlike many comparable systems, Paligo relies on structured documentation creation with a DTD (DocBook). And unlike many other systems, it can be used out of the box without extensive customization. Paligo creates print as well as online documentation and is not limited to the documentation of hardware or software. This review shows what the special strengths of Paligo are and for which scenarios the system is particularly effective.

Notes: This review was sponsored by the manufacturer of the software. However, the manufacturer did not influence the content of the review. The version tested was “March 2023 release”.

System requirements and installation

As a software-as-a-service (SaaS) application on the web, Paligo needs no installation, has no special hardware requirements, and runs on any operating system.

A standard monitor with 1920×1080 pixels is sufficient for work, although a higher resolution can still avoid some clicks when writing and provides a better overall view of the edited text.

Structure of the program window

The user interface looks quite unspectacular at first glance, and that is exactly its big advantage. Although Paligo is a rather powerful authoring tool, the interface is clearer than in a usual office program. Still, the handling is quite efficient.

When writing, concentration on the content is not unnecessarily impaired. No space is wasted, yet everything looks very tidy and clear. At no point does one feel overwhelmed by too many options. In terms of usability, the manufacturer has definitely achieved a masterpiece.

As in most editing systems, the project management is located on the left side, the work area in the middle, and the respective parameters related to the current program situation on the right.

Around everything, there is still the browser window, which unfortunately cannot be avoided in a web application – except in full-screen view.

Editing content

Anyone who has already created structured documentation according to a DTD such as DocBook will find their way around Paligo's editor almost intuitively and will be surprised at how simple structured documentation creation can be.

Those who have not yet created structured documents will initially stumble over not being able to format the entered texts as usual. Unlike in Microsoft Word, for example, a text is not first written and then formatted. In a structured authoring tool like Paligo, the text is not formatted at all – at least not by the author. Instead, before writing, authors consider which functional element they need, such as a warning. They then insert this element into the document and fill it with content. The authoring system takes care of the correct formatting depending on the element used and on where the element is placed. Example: If a warning is in the body text, it is left-aligned. If it is within a list, it automatically gets the correct left indent.

Not every element makes sense everywhere. For example, it would not make sense to use a heading in the middle of a step-by-step instruction. Then this is not possible in Paligo. As a basis for the elements and rules, Paligo uses the well-established DocBook DTD.

Inserting and editing the elements may be a bit unfamiliar at the beginning, but basically it is not more complicated than writing in a WYSIWYG editor. If an element requires several nested objects, Paligo takes care of that automatically. For example, there are comfortable editing functions for tables, just like in a "normal" word processor.

In the right pane, you can optionally assign the attributes supported by the respective element.

It is often said that a major advantage of structured authoring is that authors are constrained to a uniform structure of the documents. However, this is only half the truth, because anyone who wants to would still have a lot of freedom to do plenty of "nonsense". Because the DocBook DTD used by Paligo is not specialized on certain documentation types or projects, no fixed, uniform structure can be specified for the documents to be created.

A more significant advantage in connection with Paligo is the fact that structured authoring makes it easier to reuse content several times, and that content and layout are clearly separated from each other. This means that, at least on the design level, a uniform look is actually guaranteed, regardless of the respective author. Since authors cannot format individually, there can be no deviations here.

Paligo is not a classic help authoring tool (HAT), although it can be used to create context-sensitive online help very well. However, managing context IDs is a bit more cumbersome than in some classic help authoring tools. It is also more difficult to implement a very individual layout in Paligo than in a classic help authoring tool.

Another thing that is not very well supported in Paligo is creating an alphabetical index. Although such an index is often no longer created today, it does make sense, particularly in printed manuals. An index can also be created in Paligo but is somewhat cumbersome compared to other systems.

Publishing documents

If a document is to be generated ("published"), its desired properties can be defined via dialogs and saved for the future. These properties include:

• format and layout to be used
• languages
• variables and conditions for conditional content

Optionally, Paligo can upload the result to a server right after generation (FTP, GitHub, Netlify, Azure Repos, BitBucket, GitLab, Amazon S3).

Paligo supports the following formats for output:

• PDF
• HTML (WebHelp, plain HTML, exports for Freshdesk, ServiceNow, Salesforce, or Zendesk)
• Word (not very suitable for further processing, because everything in the document is fixed formatted, without using paragraph and character styles)
• eLearning (SCORM)
• XML (DocBook)

Exporting to DocBook is in principle also a way to migrate content to another authoring tool or for another creation process in case you no longer want to use Paligo. However, this should not obscure the fact that there is always a significant loss of metadata associated with it. While all the data in a given document is exported cleanly, the entire "single source" is not. In particular, data exported in this way lacks information about which information originates from content modules that are used multiple times. For example, if a certain warning appears ten times in a document, but is included once in the Paligo source data as a multiple-use module, the export will end up with 10 copies of this text. If this is then imported into another authoring tool, the advantage of having a central module is lost there (unless the system is able to identify such duplicates and build up its own modules again in the process).

PDF output

The PDF output supports everything that makes up a professionally designed manual and leaves little to be desired.

WebHelp

The WebHelp output also offers everything that is common in modern online documentation – in some details, it offers even a little bit more.

Important: Although Paligo itself is a web application, the online documentation it generates is independent of it and can be installed on your own web server or locally on a user's computer. In this respect, Paligo is fundamentally different from a classic wiki or knowledge base.

The WebHelp output supports in particular:

• responsive design
• clickable images (thumbnail images, lightbox)
• expandable sections (dropdowns, toggles)
• MiniTOC (page navigation)
• user sortable tables
• tables with sticky headers and column filters
• fuzzy search

There is also a layout option specifically for API documentation. Here, users can view code examples in different programming languages parallel to the content (image taken from Paligo documentation).

Faceted search

Paligo even supports taxonomies, which in principle makes it possible to implement a faceted search in online documentation. This enables users to filter the documentation at runtime according to certain criteria.

Unfortunately, this is not supported in the standard output created with Paligo's on-board tools. If you want to implement a faceted search, you need either a content delivery platform like FluidTopics or Zoomin, or an external search engine like Algolia or Swiftype.

However, unless the respective system is already being used elsewhere, this involves considerable additional licensing costs.

The following example shows an online documentation delivered via Zoomin:

Single source publishing

The possibilities to use content that has been created once multiple times are outstanding in Paligo. This is because all content is stored in a database and because layout and content are cleanly separated in the structured source data.

Multiple use

Multiple use of content is possible not only within a document but freely across all document boundaries. Anything that exists anywhere in the database can be reused at any other point. If something changes later, only one place in the source needs to be edited. All places that also use the same source are automatically up-to-date again.

• A topic can be used within any number of publications.
• Certain content (topic, snippet, paragraph) can be used within any number of topics.
• A structure can be reused within another structure.

At the push of a button, it is possible to see where an element is used. It is not possible to delete an element that has been used multiple times (unlike in some simpler authoring tools, not even in the case of cross-document reuse).

Conditional content

Paligo supports conditional content for all elements. If a condition is assigned to an element, the element is only visible in a publication if this condition has been activated for this publication.

In this way, it is possible to create different variants of a documentation that differ in detail. For example, it can be used to hide a certain paragraph in a certain variant of a documentation. Or there can be several variants of a paragraph, of which a different one is displayed depending on the documentation variant.

Variables

A variable is only assigned (document-specific) content when a document is generated. This can be a product name, for example. In one document the product is called "A", in the other document "B". Otherwise, the content is the same and therefore does not have to be entered and maintained multiple times.

Conditional content and variables are supported in a similar form by almost all authoring tools for creating technical documentation. A special feature in Paligo, however, is variables for images. Similar to a text variable, several variants of an image can be stored. Images can also be displayed as variant-dependent using conditional content, but image variables make this even more convenient.

Translation

The manufacturer of Paligo is based in Europe (Sweden). Here, the matter of translation of documentation is particularly important, and you can see this in Paligo. The support for translations and for multilingual documentation is excellent:

1. Content to be translated can be exported to a translation package in XLIFF format at the click of a button.
2. You send the translation package for translation. In Paligo, the corresponding items are locked during this process, so a new version can’t be created in Paligo while the content is still being translated.
   Note: If necessary, a new branch can be created via version management, so that parallel further work on the project is still possible.
3. Translators translate the content using any translation memory system (TMS), so they do not need access to Paligo. Things that have already been translated for previous versions or in other places do not need to be translated again thanks to the TMS, but are taken from the memory of the TMS.
4. You import the translated data back into Paligo at the click of a button.

If required, content can also be translated directly in Paligo or exported to some other formats for translation. But these are only special cases.

Support for multilingual projects is also excellent when it comes to publishing. You don't have to create publications for each language individually but can assign which languages each publication should contain. Paligo then generates all languages in a single step.

In addition, you can choose whether a separate document should be created for each language – for example, a separate PDF file or separate online documentation – or whether the result should be a multilingual document. All this is supported with on-board tools and does not require any special customizations.

• In a multilingual manual, the various languages follow one after the other in the same PDF file. In the margin, a tab shows the respective language (image taken from Paligo training video).
  

• In multilingual online documentation, users can change the language via a drop-down list (image taken from Paligo training video).
  

Teamwork

As a web-based authoring tool, Paligo is predestined for efficient team collaboration. Hardly any wishes remain open here. The biggest plus is that for people who are only sporadically involved in the project, the user interface remains very simple and no major training is required. But even for authors, collaboration is not complex.

• If a person is working on a topic, Paligo automatically checks this topic out of the database and checks it in again later. While checked out, other users cannot edit the topic, so no conflicts arise.
• For persons who are to review created content, there is an extremely simplified user interface in which the reviewers can view and comment on the content assigned to them individually or as a user group.
• For subject matter experts, unlike for mere reviewers, there is a simplified interface to also edit or create certain content themselves.
• Authors decide which contributions from the participants are permanently included in the documentation and edit these contributions as required.
• Integrated user management functions allow you to control exactly who has access to what.
• An integrated task management function can be used to assign and manage specific tasks for individual persons.
• The separation between content and layout ensures a uniform appearance regardless of the author.

Versioning and branching

Paligo does not work with external version management systems commonly used by software development. Instead, it has an integrated version management system that is specifically designed to meet the typical requirements of editorial projects. All common mechanisms such as branches, forks, merging, etc. are supported. This makes it possible to maintain two or more versions of a documentation at the same time without having to duplicate content unnecessarily. Later, the versions can be merged back into one version.

In an online documentation created with Paligo, multiple versions of a documentation can be made available at the same time so that users can be offered to choose which version they want to see (image taken from Paligo documentation).

The system saves a full history of all changes for all elements down to paragraph level. So you can always see who made which change and when, and it is always possible to restore an earlier status.

When comparing two versions, Paligo shows only the XML source code, not a WYSIWYG view. For authors who are used to a version comparison from Microsoft Word, for example, this may take some getting used to.

Data migration

How well or less well existing data can be migrated from another system always depends heavily on the quality of the data in question. This is also the case with Paligo. Which workflow and which degree of automation are economical must always be determined on a case-by-case basis.

In general, Paligo supports the import of the following formats, but it does not always support all features of each format. So all texts may be imported, but not all formats or functions:

• Author-it
• Confluence
• DITA
• DocBook
• HTML
• Help+Manual
• Madcap Flare
• RoboHelp
• Swagger OpenAPI
• Word
• Zendesk

Customization

Content and layout are kept completely separate in Paligo, which generally facilitates applying different designs depending on the publication.

The design of the generated documents to your own corporate design works very easily – as long as you stay within the possibilities provided for this purpose. In the layout configuration, there are numerous parameters depending on the format. In a preview, the result of the current setting can be seen immediately.

Most standard requirements can be implemented in this way, but no special things. If these options are not enough for you, you still have the following possibilities:

• For the PDF output, deeper adaptations are difficult to make and only possible by adapting the internal transformation processes (XSLT).
• For HTML output, you can include your own CSS file and thus overwrite the system-generated styles.
• For HTML output, you can also include your own JavaScript and use it to change system-generated things at runtime. The documentation suggests using this method if you need to add your own header or footer, for example. This may work, but it could be more straightforward. An editable HTML template, as in some other authoring tools, does not exist.
• Finally, as an online documentation generated from Paligo consists of static HTML, CSS, and JavaScript files, it is always possible to use some post-processing after the generation of an online documentation to replace or to add certain things manually or automatically.

What is not possible in Paligo (in contrast to many classic help authoring tools), is to insert your own HTML snippets at any place within a topic.

API

Where Paligo's on-board features end, its programming interface (API) comes in. It can be used to access Paligo and its data from other programs. For its various integrations with third-party systems, Paligo itself uses this interface heavily. If required, you can create similar integrations yourself for your own programs and processes, or you can have it created as a service.

Some typical use cases cited by the manufacturer for this are:

• batch import of large amounts of data, especially when repeated
• transfer of data (text or images) from databases and other systems
• synchronizing data between an external system and Paligo
• publishing to additional channels
• automated publishing at specific times
• implementation of an automated, agile translation process
• ...

The bottom line

Paligo is one of the few web-based authoring tools for technical documentation that can withstand even demanding requirements. Unlike most comparable solutions, Paligo relies on structured authoring with the help of a DTD (DocBook). Yet, it is very easy to use. Also outstanding are the possibilities for reusing content once it has been created.

Other features of Paligo that should be emphasized are its integrated translation management and its integrated task and version management. A special feature of Paligo is its various integrations and output options to third-party systems, such as the content delivery platforms Fluid Topics and Zoomin, to powerful search engines such as Algolia and Swiftype, and to helpdesk systems such as Salesforce or Zendesk.

As a web application, Paligo inherits the classic advantages and disadvantages of any web application: The system works independently of operating systems and special hardware. The effort for installation, maintenance, and backup is zero. On the other hand, the source data for the documentation is not stored in-house, and it is not possible to work with the system without having access to the Internet. When working in Paligo, the browser also consumes a certain amount of screen real estate, and even with a fast Internet connection, there is always some degree of latency. For most work, this is minor, but it can slow you down when clicking through many objects quickly. The browser also gets in the way when using keyboard shortcuts.

If you "only" need to create a single documentation of a few hundred pages, Paligo is clearly too large. Paligo is also less suitable if you want to work very flexibly and like to be able to tweak every detail yourself. This simply contradicts the principles of structured authoring and a ready-to-use SaaS solution.

The more of the following factors apply to your situation, the more likely you are to be happy with Paligo, and the more cost-effective it is to use Paligo:

• large number of documents
• large amount of overlap between documents (high reusability of content)
• multiple languages
• multiple persons involved in the creation and review of the documentation, possibly spread over various locations
• decision for structured documentation authoring using a DTD, but without the requirement for having an individual DTD
• desire to focus on producing content and not having to deal with design and technical issues
• use of one or more of the available integrations with third-party systems supported by Paligo

Pricing and licensing

Like many of its competitors, the maker does not publish prices on its website, but merely an overview of the available license models. However, Paligo actually does not need to hide in terms of price. Upon request, the pricing model is very transparent and as a SaaS solution, Paligo can be used productively from day 1 and does not require any lengthy and expensive implementation phase.

Manufacturer and licensing options: paligo.net