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.
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.
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.
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.
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”:
LiquiDoc CMF Landing Page
LiquiDoc CMF Documentarian’s Overview (Slides) (Onesheet)
LiquiDoc CMF Administrator’s Overview (Slides) (Onesheet)
A Tour of the ajyl.org LDCMF Repo
A Tour of the Digi Embedded LDCMF Repo
DocOps Evaluator Decision Matrix
LDCMF Proving Grounds (FAQ) (Demos)