LiquiDoc CMF (LDCMF) is a “content management framework” — a set of tools, conventions, and standards for sensibly organizing and maintaining source content and data as well as producing deliverable artifacts. The LiquiDoc/LDCMF User Guides project covers the general use and maintenance of LiquiDoc and LiquiDoc CMF. Here we’ll preview its main features, focusing on how they’re implemented in this project (LiquiDoc/LDCMF User Guides).

LDCMF: Not Your Daddy’s Content Platform

LDCMF is likely to seem unfamiliar. It is a publishing platform but not a content management system (CMS) nor a component content management system (CCMS). It differs from these mainly in that it does not revolve around a database or a user interface designed for a specific type of content or publishing.

LDCMF is designed for flexibility, in order to meet the demands of complex documentation projects that cover potentially numerous versions of multiple products for various audiences, perhaps yielding artifacts in two or more output formats, as well as other complicating factors. The platform enables a docs-as-code approach to technical content, whereby the documentation source material is tied to the product source code, as well as using tools and methods more familiar to developers than to writers.

Pros/Cons of LiquiDoc CMF vs Proprietary CMS/CCMS Solutions

There are several major differences between an open-source docs-as-code approach to creating, managing, and publishing technical documentation. Whether they are pros or cons in your book may depend very much on whether your background.

Some assembly required

Users are expected to heavily customize and extend their LDCMF environment rather than fall back on “turnkey” features and elements. While you can technically write and build a pretty straightforward docset based on existing, freely available LDCMF examples, your needs will almost certainly vary. The free-and-open model adhered to by the framework means you will never encounter a dead end imposed by the LDCMF platform. Hopefully you won’t need to actually modify or extend the base tooling to solve your needs, but you will need to configure a complex docs build if you have complex problems. Presumably, that’s how you ended up here anyway.

Small data is simple

LDCMF’s sources of data and content are far simpler than conventional CMS applications. Stored in flat files and directories rather than relational databases (RDBs), LDCMF’s relatively flexible and casual datasource options have their limitations. Most conventional CMS platforms take advantage of RDBs’ powerful indexing and querying capabilities, not only handling content and data but managing large amounts of site and content metadata. On the other hand, RDBs cannot be used with distributed source-control systems like Git.

GUI? What GUI?

LiquiDoc CMF’s user interface is command-line tools (CLIs) and free, open-source text/code editors, rather than proprietary desktop programs or web apps. For some, this is the epitome of power and freedom. For others, these blinking-cursor options are intimidating to the point of paralysis. While LDCMF can be deftly operated by beginners with both kinds of tools, there may be some initial discomfort. But then: total freedom and power!

What Do I Need to Learn?

First, be sure you’re looking at the guide for the proper role (Developer). See ldcmf-user-roles#,Understanding Your Role as Developer to be sure.

As a developer, you have the ability to extend or modify either the LiquiDoc build utility or the LDCMF content framework.

Each has a distinct Git repository.

To modify the LiquiDoc Ruby gem, you will need some familiarity with Ruby.

The LDCMF repo, on the other hand, is merely a set of directories, static files, and documentation. The most complicated languages are YAML, AsciiDoc, and Liquid.

To be most helpful hacking LDCMF, you also need to be familiar with the documentarian role, as covered in the LDCMF Documentarian Guide, and the admin role, covered by the Administrator Guide.

LiquiDoc and LDCMF Overview

The LiquiDoc CMF platform relies on the LiquiDoc build utility, which in turn employs other open-source applications to process and render rich-text and multimedia documentation output.

As should be clear from the comparisons key to LDCMF-based documentation projects is managing all content and data in plaintext (“flat”) files rather than a database. The primary source formats for an LDCMF project like this one (LiquiDoc/LDCMF User Guides) are AsciiDoc and YAML.

AsciiDoc

Dynamic, lightweight markup language for developing rich, complex documentation projects in flat files. (Resource)

YAML

A slightly dynamic, semi-structured data format for key-value pairs and nested objects (Resource)

These formats are chosen for efficacy, learnability, and readability, and this guide will walk you through the steps you need to get comfortable and proficient with them, including plenty of supplemental resources. Before diving into AsciiDoc and YAML, let’s keep exploring just what LDCMF is.

LiquiDoc CMF is used to build various types of documentation, but it excels at multi-format output, such as generating a PDF edition and a website from the same source files.

The Intimidation Factor

Instead of web forms with text fields, selectboxes, and WYSIWYG editors; LDCMF offers a bunch of text files. The advantages may not be self-evident yet, but let’s address the elephant in the room: this all seems a lot harder than it should be. It will sometimes take more work to manage docs in plaintext files using what will at first feel like crude editing tools, not to mention that clumsy command line.

While LDCMF’s usability will steadily improve, it will always require technical writers and documentation managers who have worked in other fields to reconceive how docs are created and managed. But you will be able to get comfortable with your new tooling, and you might even come to appreciate it. Nothing we can say here will take the pain away, but rest assured this documentation is written with beginners in mind.

GitHub

This project is intended to be managed using GitHub, the most popular cloud service for Git repository hosting. You will need a GitHub account to fully participate as a contributor.

Unfortunately, GitHub’s friendly user interface will only handle some of the procedures you need to perform in order to commit to documentation.

which manages source-code in a distributed fashion as the codebase evolves. Managing content directly with Git allows documentation to more accurately align with the product it covers, a key objective of LDCMF. If you have avoided Git so far, your number may be up. There’s great news: Git is a highly marketable skill with an ever-widening range of applications in various sectors, fields, and roles. Once you experience it’s potential in the world of documentation, you will understand what everyone is so excited about.

In the case of the LiquiDoc/LDCMF User Guides project itself, we’re generating a PDF “manual” and an HTML “portal” for each of the following “guides”:

Tags: