elucid8 (pronounced 'elucidate') provides utilities to create, manage, and maintain a set of complex documents that explain how to use a product in multiple languages. A complex document is one that contains multiple headings, cross-references, tables, images, words to be indexed, footnotes, and other types of information.

The complex documents are created and maintained in RakuDoc v2. The suite is written in canonical human language (e.g. English), and there are translations of the suite in other human languages (e.g. French, Spanish, Chinese), which are called the derived languages.

It takes a directory of canonical files, directories of derived languages, renderers them all into HTML, and creates the links between them so that a user can switch between languages at the section level (a section is one started by a heading). The link to a target language is presented in that target language.

elucid8 is a Free Open Source Software (FOSS) distribution.

Motivation

The are very many CMS (Content Management Systems) available today. Many of them offer multilingual functionality. Websites have proliferated, and companies now are obliged to maintain documentation on-line.

It is relatively easy now to create a website that combines some text, images, and blogs. Even a novice website designer can achieve effective websites because of themes and skins that place simple text component, and images together.

It is not so easy to create a website when the underlying document is complex. Corporate professionals are used to creating complex documents in programs such as MSWord or LibreOffice, with Tables of Contents, Indexes, Tables, Diagrams, etc. Transferring these aspects to the web is tricky, time-consuming, and error-prone. These challenges intensify when language translations are part of the requirement.

elucid8 is a framework to assemble and to publish consistent information.

Workflow

            canonical directory  -|
            derived 1 directory  -|
            derived 2 directory  -|                          | interlinked HTML pages
                                  |->  elucid8             ->|
                                       |-> RakuDoc Render |

Each directory contains many files in RakuDoc markup. They are rendered one-by-one by the renderer, and then linked by elucid8.

When a change is made to a file in the canonical directory, corresponding sections in the derived files are styled to show a change is needed.

Each derived file can be separately edited by one person, or across a documentation & translation team. Editing a derived file, changing an altered section, removes the styling.

Applicability

Rakudoc is an easy-to-use markup language for document formatting. It was originally introduced as "POD6" for use with the Raku programming language. However, all along, its design with the use of metadata options, and its customisability make it far more than just a tool for software documentation needs. This general capability was dubbed "Plain Old Documentation".

It is applicable to a wide range of situations from a single page that needs translating into a handful of Western languages to documentation suites of hundreds of pages and translation into dozens of natural languages with deep support for non-Latin text and the Unicode standard.

elucid8 helps to simplify workflows, save time, avoid errors and save costs.

Many industries and organizations require multi-language documentation to cater to global audiences, comply with regulations, and improve user experiences. Here are some prominent examples:

• Technology and Software Development
• Healthcare and Pharmaceuticals
• Manufacturing and Engineering
• E-commerce and Retail
• Education and E-learning
• Legal and Financial Services
• Government and Non-Profit Organizations
• Travel and Hospitality
• Media and Entertainment
• Energy and Utilities

Organizations:

• Multinational Corporations
• Export Businesses
• Educational Institutions
• Healthcare Providers
• Regulatory Bodies

Community

Please do join us on the elucid8 chat server on Discord! We warmly welcome contributions and support requests (please file an Issue) over at GitHub.

Background

RakuDoc was created together with the Raku language. It is open to any programming langauge and already supports Perl and JavaScript software documentation needs. Many elements of POD6 (i.e. version 1) were undocumented and were not implemented. It became clear that an updated specification was needed and recently Rakudoc v2 was released. There is now a generic renderer which transforms Rakudoc v2 into text output, HTML output, and MarkDown output which is the underlying engine for elucid8.

Rakudoc is a textual markup language like Markdown. In common with Markdown, it offers text-based embedded markup which helps with readability and compatibility with workflows such as difference checking, merging and translation (unlike most WYSIWYG Word processors, where the formatting is hidden). However, unlike Markdown, RakuDoc can easily be used to specify a complex document with inline and block level options and it does not suffer from incompatible variants.

elucid8 is a new solution framework bringing the benefits of Rakudoc to a wider audience.