A Multiplatform Toolset for Markdown Checklists – InApps 2022

GitLab sponsored this post.

This article is the third of a series. Part 1 justified that human-performed DevOps checklists are essentially source code, and according to GitOps principles, belong in Git just like any other code required for successfully managing a software stack. Part 2 dug into the rich but often overlooked, support for interactive checklists on GitHub and GitLab. In this article, we dive into the why and how of using rich desktop editing tools for checklist creation and completion.

Checklist Authoring, Navigation and Completion without Dual-Pain Markdown Editors

“Dual-pain” is not misspelled here — while developers may consider a live rendering window an upgrade to coding in raw markdown, it is very cumbersome for those who do not have a developer role, but need to author Template Checklists or complete Tracking Checklists.

The interactivity of checklists on GitHub and GitLab should generally be used for Tracking Checklists as they facilitate collaboration through immediate, shared updates and do not require Git commits or merges during real-time operational events.

There may be times when visual, desktop-based utilities offer advantages over this model, such as:

• For easy authoring of checklists.
• For navigation of complex checklists In an outline mode while completing them.
• For completing visual markdown structures that are not interactive on GitHub and GitLab (such as fill-in fields or tables).
• For implementation of more elaborate “completed marking” (for example, adding date-time stamps and/or colors).

Typora + CopyQ

Combining Typora and CopyQ expands checklist execution and authoring options. CopyQ allows the insertion of standardized markdown snippets using hotkeys and Typora can directly receive markdown and immediately renders it. This allows adding the following additional completion marking capabilities:

• Apply Markdown formatting completion mark (such as bold).
• Insert the current date and time as part of “Completion marking.”
• Prompt for information and include it as part of the insertion text. In the provided CopyQ code there are examples of prompting for both Template Checklist authoring and Tracking Checklist execution.
• Apply HTML or CSS formatting — for instance, colored text background. HTML and CSS formatting render nicely in Typora, but not in GitLab and GitHub.

Cumbersome Markdown Editing Eliminated

In the past I have had my favorite code editor (VS Code) loaded up with many markdown extensions — each one completed different parts of the puzzle and did it in different ways. Sometimes they conflicted or even prevented editing the markdown by no longer recognizing specific keystrokes. I have removed those plugins and instead run a plugin that simply opens a file type in my operating system’s default application for markdown files and configure Typora to handle markdown extensions in the operating system.

Recording Information in Checklists and Cognitive Loading

The elimination of cognitive load during a stressful activity, such as managing IT changes, is also a huge benefit. No matter how sharp you are, humans have limits as to how many things they can juggle in any situation — but the sheer risk of production changes saps even some of that capability away because we are being extra vigilant to ensure everything is done just as planned. Under these conditions, getting some markdown code wrong or having to keep recalling the need to properly format can be very distracting.

A primary way around this dilemma is to prepare a copy of a template checklist in advance of the change event to the degree that it is possible. Filling in versions, titles, change dates can usually be done a few days ahead of time. Typora can be used for this by simply copying the body portion of an Issue or Merge/Pull Request in, and when done, pasting it over the body content when done editing.

If your checklist execution procedures require the insertion of screen captures, log data or inserting names and dates and versions — then editing the markdown will be required and this is where Typora will shine by making it nearly as easy as using Google Docs or your favorite word processor. Using Typora for execution does not allow easy real-time collaboration — so there is a potential trade-off if the checklist is used collaboratively.

Multiplatform Developer Workstations for DevOps

Across my professional and personal projects, I use all of Windows 10, Mac OS (Catalina) and LinuxMint for editing code and markdown. I use Visual Studio Code on all of them as my primary text editor. These operating systems are also common across DevOps teams — many times the same team will have at least two of these.

Typora and CopyQ both run on all three OSes as well and provide a consistent user experience on all platforms.

Cost of This Solution

Paid for checklist SaaS solutions can represent a lot of adoption friction for team tooling — not just because of cost, but due to:

• Establishing new system users in a third-party system.
• Having important audit records in the care of yet another third-party.
• Can not integrate directly with the built-in checklist interactivity of GitLab and GitHub.

Typora and CopyQ are free and there are no other elements to the solution that carries a cost.

CopyQ for Standard Markdown Checklist Snippets

If you have team members or teams who do not like Typora, CopyQ can provide value by itself in that a standardized set of Markdown insertions can be defined and shared via a CopyQ configuration text file in Git. This can allow the establishment of some conventions for authoring and executing checks regardless of the editor in use.

Per-Step Time-Date Stamps on “Done Marking” Required

Time-date stamps on “done marking” may be desirable or required by your checklist execution methodology. Some checklists may be multiday or long-running — even if completed at one time. Time-date stamps add value by creating a historical time record of completion time and elapsed time — which allows for predicting ops events duration and event correlation if there are problems with a change.

As mentioned earlier, GitLab’s markdown interactivity does provide these stamps in the discussion log — however, if you ever had to audit a checkbox for completion or timing — you must review the entire log for all toggles of the checkbox in question to get the information. In addition, if you have checkboxes that have the same text repeated, it will be difficult to sort out which ones are being manipulated in the audit log.

When to Use Typora Over Other Editors or Web Editors

• For authoring checklists — even when they are stored as issue or merge/pull request templates.
• When advanced formatting is desired or required — you will be more willing to author helpful constructs such as tables and inserting graphics. Inserting graphics using Typora is especially compatible with git by allowing you to seamlessly copy the inserted graphic to the same directory as the markdown where you are inserting it.
• For completing checklists that have a lot of data recording or where more sophisticated done marking is required. This inhibits real-time Collaboration on the document because you have to go into edit mode in the issue or merge/pull request.

Working Example of What Is Possible with Typora and CopyQ (with Code)

The premade stamps provided here all have CSS colors — but also use standard markdown bold so that they stand out reasonably well with or without CSS rendering.

Setting Up Typora and/or CopyQ

The following instructions have been tested on Windows 10, OSX and Linux (LinuxMint 19.x).

Installation on Windows (Chocolatey)

Installation on Mac (Brew)

Installation on Linux (Ubuntu)

Typora is only tested on Ubuntu.

Here are the Linux installation instructions:  http://support.typora.io/Typora-on-Linux/

CopyQ in public package repos is published as “CopyQ”: https://copyq.readthedocs.io/en/latest/installation.html

Configure Typora

These settings are optional, but helpful for the concept of Markdown Checklists. Access these settings from File => Preference:

**Images Insert** => “Copy image to current folder (./)”
**Save & Recover** => “Auto Save”
**Privacy** => “Send Anonymous Usage Info”
Configure CopyQ with TODO, DONE, SKIPPED and RECORD HERE Stamps

The following snippets give you a minimum to start with and also serve as examples to customize for your own work. Using the technique of distributing your own command ini allows you to standardize across your team.

While we are pairing CopyQ with Typora, it works fine with any Markdown editor.

Import this CopyQ settings import file: https://gitlab.com/darwinjs-ideas/GitOpsforHumanProcessedChecklists/-/blob/master/copyq-command-import.ini

1. Start CopyQ from the menu and it becomes memory resident.
2. If the UI does not show, open CopyQ from your “tray” area by clicking the icon and selecting “Show/Hide.”
3. In the CopyQ UI, Open “File => Commands / Global Shortcuts.”
4. Use the “Load Commands” button to load the INI.

Here are the hotkeys. They render with background colors in Typora (renders CSS) and without the background color on websites like Github and Gitlab. The bold and square brackets make the stamps recognizable when colors are not rendered.

•  ALT-SHIFT-S: **[TODO]**
• ALT-SHIFT-D: **[DONE 07/28 @ 10:42]**
• ALT-SHIFT-Z: **[SKIPPED 07/28 @ 10:42 <whatever was typed in response to the prompt>]**
• ALT-SHIFT-X: **[RECORD RESULT HERE]**
• ALT-SHIFT-R: _REPLACE_WITH_ <whatever was typed in response to the prompt>

Tested On

• Windows 10
• MacOS
• LinuxMint 19.1

Conclusion

This article series has set out to communicate some foundational ideas about managing DevOps procedures in a GitOps world.

First, we established that the “human code” we find in our DevOps solutions is just as critical as computer code and therefore belongs in git.

We went on to claim that “human code” can be recognized because it takes the form of checklists, which reassemble computer code in that they are exacting, ordered and sometimes conditional instructions for accomplishing the desired outcome.

We touched on the evidence-backed claims in the highly recommended book  “The Checklist Manifesto” that the helpfulness and necessity of checklists positively affect all individuals and teams no matter how smart they might be.

The templating and interactive checkbox features of GitHub and GitLab were highlighted as critical enablers for integrating of checklists into GitOps software change-management workflows and serve as working example repositories on both were also provided.

Finally, we discussed some rich multiplatform desktop tools to help with ease of editing and standardization of Template Checklist creation and Tracking Checklist completion. Working code examples for configuring CopyQ were also provided.

It is my hope that this three-part deep dive will help you, your team and your organization to experience the massive quality improvements that the simple concept of collaborative checklists has to offer.

Code, Examples and Architecture for This Article Series

“GitOps for Human Processed Checklists (Part 1)”

“GitOps for Human-Processed Code (Part 2): Interactive Markdown Checklists on GitHub and GitLab”

CopyQ command import file for stamps discussed in this article.

Product Selection Architecture Map For This Solution

“Architecture Heuristics for This Solution: Requirements, Constraints, Desirements, Serendipities, Applicability, Limitations and Alternatives”

GitLab Sample Repository

GitHub Sample Repository

“The Checklist Manifesto”

Feature image via Pixabay.