LiquiDoc CMF Guides Project

This codebase is the source for publishable artifacts that document three subjects: AJYL docstack, LiquiDoc, and LiquiDoc CMF. The entire canonical output of this repo is hosted at https://www.ajyl.org, with specific artifact URLs below.

Overview

You will find in this repo the source for numerous artifacts, including differently formatted “editions” of our core user guides, as well as outreach materials intended to help introduce and popularize LiquiDoc.

Note

The source data and content for this repository are oriented toward AJYL docstack, LiquiDoc, and LiquiDoc CMF, but the entire project was developed with your own project in mind. If you are developing or administering a LiquiDoc-based documentation project, the contents of this repo may not only be instructional. Instructions are provided for cloning this repo and reorienting it to provide internal and customer-facing docs for your project.

This README

Please note that the file you’re reading contains instructions for setting up an instance of the LDCMF Guides docs, NOT your documentation repo itself (unless you’re working on the LDCMF docs). The docset these instructions establish (see Core Artifacts) is a duplicate of everything hosted at ajyl.org. Those documents are meant to orient and instruct general use, installation, configuration, and modification of LiquiDoc and LiquiDoc CMF. If you are getting set up with another implementation of the LiquiDoc Content Management Framework—​such as a docset instructing the use, installation, and hacking of a product you help develop/document—​see the README for that implementation.

Core Artifacts

The codebase in this repository generates the following artifacts.

• Documentarian Guide Web Portal | PDF Manual | HTML Manual

• Administrator Guide Web Portal | PDF Manual | HTML Manual

• Developer Guide Web Portal | PDF Manual | HTML Manual

The Documentarian Guide provides general instructions for using LiquiDoc to build your project’s documentation, mainly in the form of actual instructions for contributing content to the LiquiDoc CMF Guides project (this repo!) itself. That is to say, if you read the Documentarian’s Guide you’ll be able to contribute effectively to this very project, and your contributions will be welcomed.

The Developer Guide meanwhile instructs how to extend or contribute to the subject producs: LiquiDoc and LiquiDoc CMF. That’s the guide for anyone interested in hacking the products. This DevGuide is not always included in other implementations, as in that context it would need to be replaced with content covering contributing code to your product itself.

The Administrator Guide contains an overview of the admin role as well as in-depth use cases, configuration strategies, and LiquiDoc references.

The following artifacts are still in the works but listed here to provide context for the breadth of this project:

• LiquiDoc CMF Landing Page

• AJYL Landing Page | Onesheet

• LiquiDoc Homepage | Onesheet

• 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)

Build

All project artifacts are generated by a sequential build procedure. This section instructions acquiring the files, preparing the build tooling, and performing a basic local build. For more thorough documentation instructions, see the docs appropriate to your role.

Prerequisites

This procedure invokes the LiquiDoc tool and in turn Asciidoctor, Jekyll, and other dependencies to build all documentation and other artifacts.

The only prerequisite software packages you may need are Ruby runtime and Git. You will also need a terminal application. The rest will be installed during the basic setup instructions.

Terminal

If you are a Linux user, hopefully you already know your favorite terminal. For MacOS, use spotlight to find your terminal, or try iTerm2.

Windows users should use the GitBash terminal installed the next step.

Git

If you are just getting started with Git, this GitHub resource guide may have something for your learning style.

For setting up Git on Windows, use the GitForWindows guide.

Ruby Runtime Environment

If you’re on Linux or MacOS, you probably have Ruby runtime. Using your preferred terminal application, check your Ruby version with ruby -v.

If you’re on Windows, use this download page. Ruby version must be 2.3.0 or higher; 2.5+ recommended, development kit not required.

Anne Gentle has provided excellent instructions for getting up and running on Windows with Ruby and Jekyll. (There are some good MacOS tips there as well.)

Install and Build

Open your preferred terminal, and navigate to a workspace in which you can create a new subdirectory for the local repository (“repo”).

1. Clone this repo.

   git clone {docs_git_origin_uri} liquidoc-cmf-guides

   Now you have a local copy of the repository files.

2. Change your working directory to the docs directory.

   Example

   cd liquidoc-cmf-guides/''

3. Run Bundler to install dependencies.

   bundle install

   If Ruby says you don’t have Bundler installed, run gem install bundler.

4. Run your first build of these docs.

   bundle exec liquidoc -c _configs/build-docs.yml

   This executes a specific build routine using the LiquiDoc utility through Bundler, basing the build procedure on a config file.

5. Serve the website locally.

   bundle exec jekyll serve --destination build/site \
     --config _configs/jekyll-global.yml --skip-initial-build --no-watch

Now you’re able to view the LiquiDoc CMF Guides web portals and associated artifacts, right on your local machine. Browse http://127.0.0.1:4009.

Full Command

Use this command to execute a clean, build, and serve operation locally.

rm -rf _build && bundle exec liquidoc -c _configs/build-docs.yml && bundle exec jekyll serve --destination _build/site --config _configs/jekyll-global.yml --skip-initial-build

Special Build Options

Here are some special flags that work with this project’s primary build config (_configs/build-docs.yml).

Build without Asciidoctor rendering (Jekyll or PDF)

bundle exec liquidoc -c _configs/build-docs.yml -v norender=true

Build without rendering website files

bundle exec liquidoc -c _configs/build-docs.yml -v nojekyll=true

Build without rendering PDFs

bundle exec liquidoc -c _configs/build-docs.yml -v nopdf=true

Repository Structure

A functional overview of key directories and files. For details, see the appropriate documentation.

ldcmf-guides/
├── _build/
├── _configs/
│   ├── asciidoctor.yml
│   ├── build-docs.yml
│   ├── jekyll-global.yml
│   ├── jekyll-guide-admin.yml
│   ├── jekyll-guide-dev.yml
│   ├── jekyll-guide-docpro.yml
│   └── jekyll-guides-common.yml
├── _ops/
├── _templates/
│   └── liquid/
├── content/
│   ├── assets/
│   │   └── images/
│   ├── snippets/
│   ├── pages/
│   ├── special/
│   │   └── assets/
│   │       ├── css/
│   │       ├── fonts/
│   │       ├── images/
│   │       └── js/
|   ├── topics/
│   └── guides-index.adoc
├── data/
│   ├── guides.yml
│   ├── meta.yml
│   ├── products.yml
│   ├── schema.yml
│   └── terms.yml
├── products/
│   ├── cmf/
│   └── gem/
├── theme/
│   ├── css/
│   ├── docutheme/
│   │   ├── _includes/
│   │   └── _layouts/
│   ├── fonts/
│   └── js/
├── Gemfile
├── Gemfile.lock
├── NOTICE
└── README.adoc

Note	In this (prime) repository, the paths products/cmf/ and products/gem/ are submodule aliases to the LDCMF Boilerplate and LiquiDoc Gem repos, respectively.

Forking & Adapting These Docs

The LDCMF Guides project has two purposes:

1. Describe and instruct AJYL docstack, LiquiDoc, and LiquiDoc CMF.

2. Provide a boilerplate for other LDCMF documentation projects to clone and adapt.

The first purpose is straightforward: these guides help you understand LiquiDoc and the LDCMF approach to developing docsets with AJYL. If that’s what you came here for, check out the published artifacts.

Among uses for this repository as boilerplate (starter) material for your own LDCMF project are:

1. documenting your own product itself and

2. documenting your own LDCMF product docs once you have an LDCMF-based docset well underway.

Option A: Document Your Own Product

The first option is to fork the LDCMF Guides project and overhaul it until all the content and data reference your product’s content and data. Unfortunately, it is highly unlikely your own product suite lines up seamlessly with the subjects of this project (a command-line utility and documentation a fledgling framework). It is therefore likely you will need to make major modifications to these docs if you want to cover your own product with them. Nevertheless, there is a good chance cloning this repo and making lots of content and even structural changes will be more convenient and efficient than starting from scratch, so you are welcome to do so. Starting from the standard, more paired-down boilerplate and init scripts is is definitely an option. Starting from the standard, more paired-down boilerplate and init scripts is is definitely an option. In other words, follow the instructions for Creating an LDCMF Project from ‘Scratch’.

Option B: Document Your Own Docs

Once your own product is documented in LDCMF, you can fork a version of these guides to use as the manual for your new documentation system. Just as these instructions serve to document LDCMF, they can be adopted to document your instance of LDCMF. You customize it to your implementation of LDCMF, then build and serve to your own site, such as an S3 bucket. To keep the docs internal, protect it by placing it on your company VPN or connecting to an authentication API.

In fact, just as this project sources its product info from its subject product repos, your forked edition of this guide can instead ingest data from your actual LDCMF setup, just as your LDCMF setup can ingest data from your own product source.

For these reasons, a lot of the LDCMF Guides content uses variables for key terms so you can quickly change the subject, audience, and context of these guides to suit your own needs. These concepts may seem extremely complex, esoteric, or simply foreign at this point, but the more you use LDCMF Guides to learn about building great documentation environments for your products, the more you will understand the strategy involved. And of course, you can always check the source to see what’s under the hood wherever we don’t explicitly peel layers back.

In this case, you will likely want to keep your fork in sync with the upstream (prime) repository, so you can absorb additions and patches without too much effort. For strategies, see Adapt these Docs in the prime Admin Guide.

Cheats

You can build a version of these guides that contains lots of additional explainer content, digging into the nuts and bolts of this complex docset, all off it built around technologies, standards, and conventions you can adopt for free. This information is too noisy and confusing for the standard guides, so we do not even publish them as artifacts. You probably shouldn’t either, as your users would be even more confused. However, you are welcome to build your own copy for reference, and you can edit the cheat notes or add your own to describe your own content and code (instead of the LDCMF Guides codebase).

bundle exec liquidoc -c _configs/build-docs.yml -v cheats=true

This can be served the same way as the conventional docs.

bundle exec liquidoc -c _configs/build-docs.yml -v cheats=true && bundle exec jekyll s --destination _build/site --config _configs/jekyll-global.yml --skip-initial-build

Versioning

The LDCMF Guides project is versioned. Each version of the guide corresponds to a version or range of versions of the LiquiDoc utility and LiquiDoc CMF. These docs may be updated numerous times in between releases of LiquiDoc or revisions of LDCMF. In the case of LDCMF, this documentation is the authoritative reference, whereas the LiquiDoc codebase itself is the source of truth on LiquiDoc utility.

Licensing

(c) 2018 Brian Dominick and Ajyl Doclabs contributors Released under the MIT License.