DevOps

DevOps - plain/text (1/2)

Many people think of DevOps as something technical, something complicated and hard to understand. But, it's quite the contrary. DevOps is based on methodologies like Lean or Kanban and aims to make the life easier. But what does this have to do with plaintext?

Daniel Schier

Dec 13, 2023 — 6 min read

Photo by Miguel Á. Padriñán

Let's investigate and see how plaintext can make your life easier in development, operations, and management.

Plaintext

First, let's clarify what plaintext is. The majority of people understands this as "can be read with a simple editor". In a security context, it also means that something is transferred or stored without encryption. Furthermore, I understand, that it is human-readable, which excludes XML or complicated source code. Moreover, the data should be easily accessible and not stored in a binary database.

The technical definition is even described very carefully. It is known as MIME type text/plain, often considered to be part of documents in ASCII format or as described in ISO 8859-n.

For the sake of this article, let's stick to the following.

editable with basically every editor
human-readable
saved as flat-file format

Why to bother?

You might wonder why I even write about this topic. As if it is important in which format one writes text. Well, actually it is. There is this concept of "cognitive load" (I might dedicate an article to it in the future), which describes that each person/team/group can only handle a couple of complicated tasks at the same time.

This concept is applicable to a lot of professions, but is exceptionally useful in IT industries. We are facing a vast, almost endless amount of tools and languages. Typically, we know only a couple of them. Knowing each and every database for example requires lots of effort. Keeping up with all updates, changes and special behaviors is almost impossible. And, do we really make use of these if we need twice as long to set them up? Or, if our pipeline is becoming complicated by having a multitude of tools in it?

Therefore, we need to limit the amount of tools and languages we are using. We can apply this "reduction of cognitive load" with plaintext. Now, let's dig into the details.

Plaintext languages

In general, one might say that every Markup language and source code are considered plaintext. Since many of them require expert knowledge, let's limit it to things that can be read without learning JavaScript beforehand.

Document languages

Some languages are excellent for writing documents. The most prominent among these are Markdown, ASCII Doc and LaTex. LaTex requires some kind of compilation to create readable documents, the others can be read by a human, even in a terminal editor.

Let's take a look at a Markdown example, first.

# Heading 1

Some text

## Heading 2

Some more text.

- lists
- are
- possible

## Heading 2

1. Also
2. numbered
3. lists

And code:

```shell
cat document.md
```

And now, compare it to ASCII Doc:

= Document Title

Some text

== Level 1 Section Title

Some more text.

* Edgar Allan Poe
* Sheri S. Tepper
* Bill Bryson

== Level 1 Section Title

1. Protons
2. Electrons
3. Neutrons

And code:

[source,shell]
----
cat document.adoc
----

Both languages can handle inline code, images, links, tables and much more. The Markdown standard is often extended by special extensions to support math expressions or footnotes. ASCII Doc on the other hand has tons of features out-of-the-box and can handle such things.

Configuration languages

Another popular plain text format are configuration files. These can come in a wide variety and several formats. The most popular ones may be INI, YAML and TOML.

INI files are popular among many software tools, known for ages, and they just get the job done.

; comment
# another comment

[section]

key = value

YAML became more popular in the last years, since it can present a tree, which offers more context. Especially the adoption in Kubernetes and Ansible, but also the fact that YAML is a superset of JSON had influence that YAML is so popular today.

# Comments

key: value

names:
  - Alice
  - Bob

translations:
  hello: hallo
  car: Auto
  house: Haus

Then, there is TOML. It is well known in some Python and Golang tools. The format can look a bit interesting and needs more context for the "general idea" of what a table is and how hierarchy works in TOML. On the other hand, it is super versatile and can produce very lean configuration files.

One might say, it is a mix of the above.

[servers]

[servers.alpha]
type = "virtual"
role = "frontend"

[servers.alpha.network]
ip = "10.0.0.1"
dns = "8.8.8.8"

No matter which configuration format you choose, all of the above can be read with almost no previous knowledge and can be understood by machines or humans alike.

Others

Now, there is more. Listing all options for different plain text formats would be a bit cumbersome, though. Let's jump over some honorable mentions.

There is todo.txt which came up with some nifty idea how to manage tasks in plaintext file formats. The syntax is mostly self explaining.

x (A) 2023-12-13 2023-12-08 Write article about plaintext +blog @home 
  (B)            2023-12-09 Check blog statistics +blog @home

Or, the Bullet journal notation, which also meant for tasks and notes:

· open task
x done task
> moved task
< moved to overview

- some note
- some other note
⃝ event

Then, there is the Changelog format, which I like a lot. It looks mostly like Markdown, but follows a defined semantic.

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [1.1.1] - 2023-03-05

### Added

- Arabic translation (#444).

And lastly, maybe old but well known by most tech people. The man page format. It's pretty damn good for software usage documentation. It needs to be "compiled", though, and therefore is not considered. So, let's say, it's an "honorable mention".

COFFEE(1)                                               COFFEE(1)
NAME
       coffee - Control remote coffee machine
SYNOPSIS
       coffee [ -h | -b ] [ -t type ] amount
DESCRIPTION
       coffee  queues  a  request to the remote coffee machine at
       the device /dev/cf0. The required amount  argument  speci-
       fies the number of cups, generally between 0 and 12 on ISO
       standard coffee machines.

Up Next

Now that we have seen a couple of formats, you might wonder how you can use these in your daily life?

Well, the article is already pretty long, and I need to continue next week with the second part. There we will take a look in modern use cases to create documentation, blog, presentations, and maybe some more.

I hope you can keep the patience. For now, let's sum it up with some links to read further.

Docs & Links

The Official YAML Web Site

TOML: Tom’s Obvious Minimal Language

Conclusion

As you can see, there is a lot to say about simple, plain, old text. Very often there is no need to come up with special formats, compiled or otherwise cryptic formats. In the next article we will take some of them and show how you can create nice looking documents, presentations and even web pages with simple text.

For now, what do you think about plaintext? Is it somewhat you are using? If so, how? Let me know, I may add your example to the next part.