AsciiDoc |
Jekyll |
YAML |
Liquid |
AJYL is a DocOps platform solution for highly complex documentation projects, solving sophisticated sourcing and output problems with a lightweight ecosystem suitable for nearly any kind of technical writing and publishing. AJYL answers the question, “What is the most capable set of technologies for implementing the docs-as-code approach to documenting and instructing software products?” No more wandering in the wilderness; you do not have to figure it out yourself.
A solution stack is only as good as its underlying technologies, so let’s explore.
The resurgent AsciiDoc markup format enables writing in elegant code (like Markdown, only prettier and with semantic features), along with limited programmatic powers, such as variable substitution, conditionals, and file inclusion. Asciidoctor is a set of highly extensible technologies and a community of developers and users, bringing the power of AsciiDoc to everyone.
Docs-as-code requires a static-site generator, and the SSG platform with the most users, contributors, and extensions happens to fit perfectly into the suite. Jekyll builds documents from YAML and AsciiDoc, and it uses Liquid as its native template engine.
Documentation is much more than written content. AJYL brings “small data” to docs: setting variables in flat files formatted as human-readable YAML. This provides much of the content-management power of databases, all stored in flat files and taking full advantage of the Asciidoctor and Jekyll rendering engines. YAML is arguably the cleanest and lightest of the semi-structured data formats, like JSON with no extraneous markup.
A good templating format and engine is the unsung hero of any fully customizable content system. For this we choose Liquid, because it is delightfully extensible and widely used by major commercial and open-source platforms, including Jekyll. Liquid empowers us to preprocess content like lists, tables, and references from our YAML small-data, as well as generate site-navigation elements and perform all manner of other text-transformation challenges.
The power and potential of this last component, the Liquid templating format/engine, would be difficult to overstate. While YAML and AsciiDoctor provide reliable storage formats for static data and content, respectively, they are frustratingly limited when it comes to truly dynamic or programmatic capabilities, especially variable text substitution, conditionals, and iterative looping.
Liquid comes to the rescue, closing these gaps with elegantly filtered text transformations, logical conditional flows, and intricately configurable looping over data. Once you are able to identify challenges that are solvable with Liquid, you will see why AJYL is flexible enough to address nearly any documentation problem you can dream up.
Tying all of these technologies together is an additional utility and a burgeoning set of conventions for implementing AJYL in production docs across numerous applications.
LiquiDoc is a build tool designed to make pulling the four component technologies of AJYL together. It provides a command-line interface and a Ruby Gem so you can integrate it into your product build system or deploy it independently.
LiquiDoc performs routines scripted in Liquid-enhanced YAML. During a preconfigured build procedure, LiquiDoc
-
copies digital assets into place as needed;
-
preprocesses new source files from small data;
-
renders HTML sites using Jekyll and Asciidoctor; and
-
renders PDF documents using Asciidoctor and Prawn.
LiquiDoc CMF (LDCMF) is the content-management framework designed to standardize complex documentation projects in order to better instruct and coordinate efforts to implement AJYL docstack. LiquiDoc can be used without this framework, though LDCMF is designed precisely to take full advantage of AJYL and associated technologies, particularly for extraordinarily complex documentation challenges.
Still a highly experimental and nacent framework we expect to (im)prove over time, we recognize there may be better frameworks out there. If you’re using these four technologies together with other tooling, or even using LiquiDoc differently, we want to know about it and point people your way.
For now, even in their infancy, AJYL and LDCMF form a reliable wheel you do not need to reinvent. The platform can solve a huge range of complex docs challenges with a minimal array of lightweight technologies to learn, all of them completely free and open source.
While the Ruby programming language is central all of AJYL’s tooling, you do not have to like or even know any Ruby programming to take terrific advantage of AJYL and LDCMF. Asciidoctor, Jekyll, Liquid, and LiquiDoc are all sourced in Ruby, and YAML is very heavily associated with these and many other Ruby projects. This is all advantageous to the stack and anyone looking to develop more tooling for it, but most AJYL users will never touch the underlying Ruby source.
However, you will have to have the Ruby runtime environment installed on every machine that needs to build your docs. This includes every documentation contributor’s personal workstation as well as integration and deployment servers.
Ruby plays extremely nicely with Linux and MacOS, but Windows users will find it frustrating at first. Since Windows is dominant in the technical writing profession, we are hard at work to bridge this gap. We believe the extra effort is worthwhile to escape the trap of proprietary tools.
The good news is Ruby makes installing and maintaining the entire AJYL toolchain trivial once it is configured. Because Ruby provides a cross-platform runtime environment, builds will work the same across operating systems.
No platform does everything, and wise developers know better than to expect the impossible. Do what you do best, and for everything else: extension and integration.
AJYL does not include components to perform several key functions, but there are options, and we have opinions. Just to show AJYL has you covered for all your docs needs, here are our answers to how to solve various elements of a complete docs-as-code toolset.
-
Source control
Spoiler alert! You’re going to want to use Git unless you have a damn good reason (and already know it). -
Continuous deployment
Since AJYL is strictly docs-as-code using open-source tools, it will work with pretty much any build/deploy system. If you have one you love, use it. If you don’t know where to start, we can help. -
Search
Cloud search providers are the state of the art here, though solutions range from self-contained JavaScript to cloud-hosted SaaS options all the way to highly customizable self-hosted search platforms.
|
Note
|
Undisclaimer
The maintainers of this document are in no way rewarded or reimbursed for endorsements or recommendations made herein.
All opinions are freely given by people who truly hope every project discussed below succeeds beyond its contributors' wildest dreams.
|
While we believe the four core components of AJYL are the ideal combination of technologies, there are of course suitable alternatives to each. Moreover, numerous complementary platforms round out a complete documentation toolchain. What follows is a list of badass projects — themselves either fully open source or extremely FOSS-friendly — which we recommend instead of or in addition to AJYL’s core technologies.
We love and believe in the growing AsciiDoc community, but you may have good reasons to try another markup format. The two most popular alternatives to AsciiDoc are Markdown and reStructuredText. Markdown is not a proper technical documentation language, as it lacks dynamic and semantic features, but shops that are already using it heavily in other arenas (in API docs, on GitHub, etc) may have cause to use it for their core docs source as well. If you are not already dependent on Markdown, for goodness sake do not get started now.
ReStructuredText is reputedly as powerful as AsciiDoc, and should be a very serious contender if the product you’re documenting is largely sourced in Python.
Truthfully, the range of legitimate lightweight markup formats is at least as big as those supported by the excellent text-conversion application Pandoc. Pandoc handles Markdown (including CommonMark and GitHub-flavored Markdown), reStructuredText, AsciiDoc, Emacs Org-Mode, Emacs Muse, Textile, txt2tags, MediaWiki markup, DokuWiki markup, TikiWiki markup, TWiki markup, Vimwiki markup, and ZimWiki markup.
A modern docs-as-code platform must make use of a data source that is accessible to the product developers and documentarians alike. This means open-source tooling and lightweight interfaces: not exactly the domain of XML- or SQL-based systems. JSON is not a terrible option, but it is unnecessarily complicated. YAML makes sense for us because it is in widespread use, including in several of the components core or akin to AJYL: Jekyll, asciidoctor-pdf, and LiquiDoc.
The suitable options include any of the various structured and semi-structured serialization formats — anything that works in a flat file (and is therefore Git-managable).
This is perhaps the richest category. Templating formats are a dime a dozen, and many of them are excellent. This Wikipedia master list is perhaps the most-definitive list. Those formats which work with Tilt might be the best place to find a Liquid alternative. If your chosen static-site generator is not Jekyll, it may require a different templating for its layout control. For instance, Hugo uses the Go language’s native templating libraries, which can be deceptively and frustratingly similar to Liquid. Therefore, if a particular format/engine is necessitated by your SSG, that might be a better choice for all your content templating (preprocessing), as well. (LiquiDoc can be extended to accommodate any templating language handled by Tilt.)
If you have a favorite solution to this category, or if you use a non-Git source-control platform, you probably know what you’re doing. For the rest, GitHub is a slight preference over GitLab, which is also doing great stuff. Most of our code and examples will be in GitHub, but both integrate somewhat nicely with AsciiDoc, so there’s no killer reason GH is better. We strongly hope GitLab and all the others succeed.
The best way to integrate AJYL is to hook it into your continuous-deployment operations. You’ll want to do this to automate at least three aspects of building docs:
-
The production delivery of the docs at your chosen interval, up to and including a deployment triggered by merging a branch to master.
-
Immediate staging of a draft edition of your docs with every merge/pull request to the repository, as well as every subsequent commit, so reviewers can review content changes without having to generate the docs locally.
-
Perform integration tests to ensure against merging docs that will break any build they’re involved in.
Platform-as-a-service provider Netlify can handle so much of this so well out of the box, you need to be sitting down when you start to explore their offerings.
Build and deploy tools are robust. If you have one you like and it can incorporate Ruby gems or perform command-line executions, you will be able to integrate all AJYL tooling. If you are just setting out to manage a documentation build, LDCMF and Netlify are the stress-free means to getting started with AJYL, from scratch to production deployment.
Developer documentation is a special beast with dozens of great FOSS solutions in the category. If your product includes native APIs, you’ll want to use specialized tooling designed to output docs for code written in that language: for instance, Javadoc for Java or Sphinx or PyDoc for Python.
REST APIs are a little different, as they are more generic for the end user (the developer integrating something with your API). The OpenAPI specification is a sourcing schema that allows developers to organize REST API information as data, in JSON or YAML format. OpenAPI-sourced docs can be rendered and delivered using Swagger. OpenAPI lets you define actual product (REST API) functionality and configuration as well as serve as source for documentation output. Swagger can even generate interactive REST API test interfaces within the documentation! If you want to push elements of your API into your AsciiDoc content, there’s a plugin for that.
As noted, most source languages have an associated API-documentation system for native extension. Wikipedia maintains excellent comparison lists of the top contenders in this category. If you are getting started with Native API docs, check out Tom Johnson’s guide to just that.
For RESTful API documentation, the main alternative to OpenAPI is probably RAML, though many claim they work best together. You’ll find an abundance of resources for integrating these tools with all elements of the AJYL docstack. You should also check out the Spring RestDocs generator, which uses AsciiDoc natively.
Every documentation site needs to be searchable. Most static-site generators use weak, burdensome JavaScipt-based frontend search that is not up to the job. Algolia provides an awesome cloud service that makes indexing easy and cheap (if not free).
These options, like Algolia, are highly customizable and will likely handle the vast majority of applications, including for complicated enterprise-scale docsets. If you need more power, however, there are excellent roll-your-own options.
Prawn is an excellent PDF rendering engine that integrates almost seamlessly with Asciidoctor (it’s another Ruby native), its renderings are somewhat limited. AsciiDoc is the recommended source language for O’Reilly books, so it can convert to excellent formats. That said, Prawn does not provide for post-processing edits. If you are particular about your PDF output, you realize any solution will require manual fine-tuning of output. Asciidoctor’s Prawn integration is quite customizable, but AsciiDoc can travel to PDF via two other routes.
If you are generating PDF and HTML from the same source, do not wander from AsciiDoc. These options might round out your toolchain.
If you don’t know what some of these terms mean, you need Cloudflare all the more!
As we take on new challenges in the world of technical documentation, this document will expand, as will the number of links detailing how to implement the various associated solutions. For now, we hope the point is made that the first elaborate FOSS technical documentation stack can handle some pretty gnarly jobs and offers excellent extensibility.
To see an active implementation of AJYL, check out Codewriting, a site about developing docs as code.