Docs-as-Code in Practice: A User's Review of adoc Studio

A few months ago, I heard the fascinating story of Leon Theremin, the inventor of the infamously eerie Theremin. The Russian inventor had a fascinating life, including eloping to America to marry an African American woman in the 1930s and attempting to resurrect Lenin. I wondered if there were more stories like this about the inventors of musical instruments, and started piecing together the idea for a book to pitch to publishers at some point.

It seemed like the perfect time and project to try adoc Studio. The app introduces several new features that are ideal for long academic texts.

Versioning and drafting

I start with the essentials, creating and iterating drafts as you review the text and get feedback. Unlike other tools you might use, such as Microsoft Word or Google Docs, adoc Studio doesn't have versioning built in and follows a docs-as-code approach. "Docs-as-code" means it uses a plain text markup language called AsciiDoc and git to create and manage document versions. Both of these techniques have a learning curve, but like many new ideas and processes, they have a worthwhile payoff.

It took a new job as an editor for an online developer portal to introduce me to markdown. A job working on a book to discover AsciiDoc, and then the ecosystem of "docs-as-code" around them slowly revealed itself.

When I was first torn away from using tools like Microsoft Word into plain text formats such as markdown and AsciiDoc and versioning with git, I was very resistant. I enjoyed the graphical toolbar and tweaking formatting and styles. I liked that everything was in one file and that almost anyone could open a Word file.

But I quickly learned that docs-as-code far more power and flexibility, and now my attitude is the opposite. I feel like an unhappy fish out of water if I am told to use Microsoft Word or Google Docs.

Using plain-text formats

In the case of AsciiDoc, adoc Studio helps you find any syntax you need by hitting the ESC key and typing into the pop-up coach. The docs-as-code ecosystem, especially AsciiDoc, focuses on semantic syntax, or "markup."

For example, instead of formatting areas of text as a table of contents, an admonition (or pop-out), or a footnote, you mark them as such and handle the formatting separately. One of my main memories of tools like Word was spending too much time worrying about what text looked like instead of its content.

AsciiDoc itself is a large topic, so if you're not familiar with it, start by reading this guide, and I cover specific syntax and features in the rest of this post.

Using version control

Unless you pay a lot of money for Sharepoint, how many times have you found yourself with multiple copies of the same Word file labelled "esoteric-instrument-DRAFT-1.docx", "esoteric-instrument-FINAL.docx", "esoteric-instrument-FINAL-FINAL.docx", etc?

Things are a bit better with tools like Google Docs, but even then, as with track changes in Word, you quickly get lost in a sea of coloured lines and comments where no one is sure of the status.

Using traditional focused versioning tools like git definitely has a learning curve, but there are many resources for getting started with git. And personally, after you get used to it, you get a level of discussion, control, and collaboration that you don't get with any other workflow.

With git, you can track small and large changes and synchronize them with other devices and people. One of the unique aspects of git is that multiple people can collaborate on a copy of the same project and combine their changes, with git mostly handling the process.

Collaborators can also create project variants and work on them independently, merging those versions back together, or maintaining completely new ones. In terms of a book project, you could experiment with different approaches to the book and decide which works for you. Or an editor could take a version and work on changes to propose to you.

Syncing between your own devices

For those who use iCloud, you can also synchronize adoc Studio documents and keep them up to date between Macs and iPads. You can keep writing on the go and have changes waiting for you, or share them via iCloud with collaborators.

Terminology and bibliography

Collating research into a bibliography

Any self-respecting academic book or book based on research needs to cite its sources. With adoc Studio, you can create a standardized bibliography section of the book with your entries and then refer and link to them from an autocomplete list as you go. If you change the bibliography entry, the linked text updates accordingly.

To create a bibliography, open the coach by pressing ESC and selecting "Bibliography," then fill in the details of the source. When you first do this, adoc Studio creates the Bibliography section in the document. With a source created, you can then select it from the link autocomplete list when creating a link.

Industrial terminology

Almost every field has a selection of jargon and custom terminology that default system or application-level dictionaries don't understand, and you have to struggle through a flood of red lines in your text.

To solve this, you generally want to be able to add custom terminology at a project level, as an unusual word may be correct in one context but not another. In adoc Studio, you can add these words to the system-wide dictionary (one advantage of being a proper macOS and iOS native application) or create a dictionary for the project and add it to that. That dictionary is another file in the project that you can share with others and manage with version control, meaning that any collaborators also don't drown in red lines.

Custom callouts

A lot of technical content, be it documentation, blog posts, or books is full of areas of text marked to get your attention. Technically they are called admonitions, but other common terms are "callouts" and "popouts". Generally these follow one of the following formats:

• NOTE

• TIP

• IMPORTANT

• CAUTION

• WARNING

For this book, I want a special one that marks out a place where the reader can find an audio sample, and this gives me a great chance to try adoc Studio's support for icon sets, specifically in this case, using Apple's SF Symbols.

First, add the following attributes to the top of the document, again hitting the ESC key brings up the coach to autocomplete all of these:

:icons: font
:icon-set: apple

These two attributes enable font-based icons and define the set to use.

Now I create an admonition, using an icon for the title:

.icon:speaker.wave.2[link=https://en.wikipedia.org/wiki/File:Epro_theremin_middle_bach.ogg]

[NOTE]

Hear a sample on Wikipedia.

Image handling and custom CSS

I like to think I am good with words, but to coin a cliché, sometimes a picture speaks 1000 words, and an image showing someone playing one of these esoteric instruments would bring life to the words.

Images come in all shapes and sizes, and as you can use asciidoc to export to different print and online formats, it's good practice to ensure you export them at an appropriate size and format.

For example, if I create an eBook version of the book, which adoc Studio doesn't support as an export target, but is essentially HTML, I want to use low-resolution images. If I create a print version, I would like to use higher-resolution images.

I also have a few formulas in the book. Take, for example, this representation of the oscillators in a Theremin:

For print, this formula needs to be rendered as an image, but for HTML, it needs to be rendered with JavaScript. Most eBook readers don't support JavaScript, so it would be better to export as a scalable image, so that the formula scales with the user's font size.

I can handle all of this with two document-level attributes, some logic, and conditional formatting.

First, I add the following logic to the top of my document, and again, all available by hitting the ESC key, which set the maximum image resolution to 100dpi and render formulas as SVGs:

ifdef::ebook[]

:ads-max-image-resolution: 100dpi

:ads-static-stem:

endif::[]

To apply these different attributes, I pass a variable called "ebook" when exporting the book, then adoc Studio applies these settings.

There are two ways to set the variable when exporting the book.

The first is from the File > Export menu, in the Attributes section of the dialog, setting the same attribute name and value.

Next, I want to change some of the formatting for the eBook version. I want to center the headings. In reality, this would be more complex, but it's fine for illustrative purposes.

To do this, open the adoc Studio > Settings menu item, and select the "Product Styles" tab.

Right Click the "Classic" style and select, "Duplicate", name the new style "eBook".

With the new style selected, again right-click and select "Edit in". If you have a favorite text editor installed use that, otherwise, use "TextEdit".

What you see here is a cascading style sheet (CSS). If you're coming from a Word background, think of CSS as the equivalent of the Styles pane. It's a place where you can define how page elements should look, and maintain those definitions in one place. It's yet another big topic, and one worth exploring, but for now, add the following to the very bottom of the file and save it.

/ Styles for eBooks /

h1,
h2,
h3,
h4 {
    text-align: center;
    font-weight: bolder;
}

This centers and bolds all headings. When you export or preview a document in adoc Studio, you can set the style to use. So when you export or change the preview settings on the far right of the toolbar, select the following:

• For print: Format to "PDF" and Style to "Classic".

• For eBooks: Format to "HTML" and Style to "eBook".

As you toggle these back and forth, adoc Studio updates the preview.

Far cooler, especially for fans of command lines and automation tools like me, is using the new adoc Studio command line command, adocstudio I can combine all of these into two commands.

For print:

adocstudio export documents --format pdf --style Classic --project Esoteric\ instruments.adocproject  --document Document.adoc ..

For eBooks:

adocstudio export documents --format html --style eBook --attribute format=eBook --project Esoteric\ instruments.adocproject  --document Document.adoc ..

Automation

Great, but why is a command-line command to export files particularly useful? Because it opens up possibilities for automation.

For example, you can use git hooks, small commands that run at various stages of the version control lifecycle mentioned earlier, to create a PDF or HTML export of the file before checking changes into a destination like GitHub, making it easier for people to review the output too.

Alternatively, with tools like Apple Shortcuts, BetterTouchTool, and Keyboard Maestro, macOS is well-suited for automation, and utilizing command-line commands opens up numerous possibilities. Even better, version 3 of adoc Studio now supports Apple Shortcuts! Here's a screenshot of the Shortcuts equivalent of the setup above.

Summary

And that's it! I appreciate that to those of you coming from using Microsoft or Google-based tools, this post bombarded you with new concepts and syntax, but hopefully it also showed you that switching to plain text formats and the toolchains and processes around them does bring a lot of power over time. Tools like adoc Studio help bridge the gap between tool ecosystems, providing graphical assistance for these powerful tools.

Guest post by:
Chris Ward, a.k.a. Chris Chinchilla
Technical writer, author, and media maker for companies large and small.