DevOps - plain/text (2/2)

One of the major misconceptions of DevOps is, that it is complicated and sophisticated. Quite the contrary is the case. It is also about reducing the cognitive load in a team and doing more with less.

Or, to frame it a bit different: It is hard, to make complex things simple. It is easy to make things complex.

Note to me: I need to explain my understanding of "simple", "easy", "tough", "hard", "complicated" and "complex" at some point in time. - sigh

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.

In the last article, I gave some ideas which file formats may be in this definition and how the syntax is looking like. This time, let's investigate how we can use these to create some cool stuff. It won't be a complete list of all technologies available, or even a comparison of the same. But, you might get a good impression how you can use plaintext formats for your team, project, or company and make the life a bit easier, yet more powerful.

Plaintext use cases

As we already found out, plaintext files are readable in basically every editor, by humans and maybe even machines. But, how can we make use out of this knowledge? Let's see some use cases and how they may help to streamline our development.

Documentation

The most obvious use case might be documentation. Sure, you can just put some kind of text in a file, and you are good to go. But, there is more.

The most popular use case is most likely the README.md. Basically every major Git hosting platform supports Markdown for parsing. Just put a simple README.md file in the root of your repository and GitLab, Gitea or GitHub will make some nice looking documents out of it. You can take a look at my profile, for example, to get an idea how this can look like.

You can extend this documentation even more when using tools like MkDocs. Every Markdown file in your docs/ directory will be transformed into a web documentation. MkDocs makes this process super easy, and you will be good to go with just two commands.

# Install mkdocs
$ pip install mkdocs

# Run a local instance
$ mkdocs serve

The results can be tweaked and tuned to your liking.

Another interesting use case is, an export to PDF files. Such a file can be used to print paper manuals, but also to offer an offline documentation. You can do this either by extending the above MkDocs with a plugin or by exporting directly to PDF. The direct export can be achieved with extensions for VSCode, many markdown editors like Marker or Apostrophe, or by using the command line tool Pandoc.

Writing

Now, we can write documentation for our code. But, how do we spread the news about the latest release, insights about our development and the upcoming bestseller about our product?

Yes, there are plaintext solutions available. Let's check some of them out.

The most popular publishing engine for (plaintext based) blogs might be Hugo. This comes mostly from the fact, that you can publish a Hugo page without a database or any other sophisticated app server. Instead, your Markdown content will be rendered to a static web page and can be displayed with any web server. Therefore, you can find Hugo pages even for GitHub pages, GitLab pages and many more. Another popular static website engine, that also uses Markdown, is Jekyll. Both can deliver wonderful results for a simple web presentation or a fully featured blog with RSS feeds, tags and customizable themes.

In case you want to write entire books, I strongly recommend checking out Bookdown and Leanpub. Bookdown is an easy way to create printer-ready books, including cover pages and everything you demand from a nice looking book. It can export HTML, ePub and many other formats to suite your needs. Therefore, you can publish to a simple webserver or even your Amazon bookshelf.

Leanpub on the other hand is a platform for authors. You will write your books in Markdown, even in a Git repository, and publish them via Leanpub to your audience. Leanpub also offers a web shop functionality, so you can sell your book via Leanpub (with a fee for Leanpub, of course) and continuously update your book. Readers will be notified about updates and new releases, too.

Organization

When it comes to organizational tasks, we might think of ToDo applications, Kanban boards and maybe even project planning. Very often, a simple list of things that needs to be done is enough.

I am using a simple file in my repositories to keep track of things I don't want to forget. With a good old TODO.md file, I don't need to open up another tool, or even the browser to get an overview of pending tasks. Such a file is pretty easy to create and maintain.

# ToDo

Some pending tasks for my project.

- [x] Create a blog about plaintext
- [x] Publish the blog post
- [ ] Check if somebody is interested
- [ ] Advertise again, one week later

This way, others can check out what needs to be done, without maintaining a huge issue tracker. Perfect for smaller projects, simple ideas, and tracking progress for the day.

A more sophisticated approach is the ToDo.txt format. It is intended to be saved as a simple, human-readable plaintext file, yet provides enough context to mark groups, projects, due dates and much more.

Aaaanyway, there is one format that needs to be mentioned here - the GNU Emacs Org Mode.

A GNU Emacs major mode for keeping notes, authoring documents, computational notebooks, literate programming, maintaining to-do lists, planning projects, and more — in a fast and effective plain text system.

This format alone can keep your entire documentation and organizational work together. There are extensions available for various editors, so you aren't limited to Emacs. Yet, you really need to learn this format. There is so much power in it, it can be a bit overwhelming at first sight.

There is more

Wait, we are not done yet. I know, the article is already pretty long and you might have something important to do. So, let me give you a quick rundown of some more tools, that might be interesting.

With Marpit, you can create awesome presentations for your next conference or solution design in Markdown easily. With nice support for images, themes and more you can export your slides to HTML or PDF and let them shine.

Bullet Journals are a great way to use plaintext formats in the digital and analog world. Track your work, notes, events and much more in a simple, convenient and easy to learn way. The community is great and has ideas for trackers, decorations, and way more. YOu can keep it simple (as I do) or be creative.

With Conventional Commits and Changelogs, you will have a terrific way to make your work more visible. Conventional Commits might not fit the definition of plaintext formats exactly, but the resulting CHANGELOG.md or RELEASE_NOTES.md are easy to maintain and can be created automagically.

All major CI/CD tools support YAML in one way or another to describe your pipeline. There is no need to maintain huge documents to describe your testing or release process, if the pipeline itself is human-readable. Be it GitHub actions, GitLab CI, Travis or Cirrus-CI, all of them handle YAML.

Automation can be done in YAML, too. As you might know, my blog is full of Ansible content, which uses YAML, too.

Docs & Links

Let me also share some other articles about this topic, that I discovered when writing the article on my own.

Definition of PLAINTEXT

the intelligible form of an encrypted text or of its elements… See the full definition

Merriam-Webster Logo

Articles

Why You Need a Plain Text Editor

Sometimes, keeping it simple is the best option.

How-To GeekNick Lewis

3 plain text note-taking tools

In prior years, this annual series covered individual apps. This year, we are looking at all-in-one solutions in addition to strategies to help in 2021.

Opensource.comKevin Sonney

Conclusion

Well, the world is full of plaintext formats, tools, and frameworks. With just some Markdown and YAML, you can automate, document, track and present your work to the outside world.

There is (most likely) no need for databases, proprietary or compiled formats. Furthermore, you can edit all of the above in your IDE and therefore use less tools, feel less interrupted and can make your documentation, presentations and organizational topics part of any review in the team.

Do you know more tools or formats? How do you use plaintext formats and files? Have I forgotten something? Please let me know. I am thrilled to learn more about this topic on my own and maybe come up with cool additions to my projects, too.