How to document when you don’t like documenting
Tags: tools, automation, devops, documentation
Published: 2024-02-26 16:40:41

---
title: How to document when you don’t like documenting
published: true
date: 2024-02-26 11:00:00 UTC
tags: Tools,Automation,DevOps,Documentation
cover_image: https://theswordblogsite.files.wordpress.com/2024/02/e0c184a707ffe30d6075a2b07024b9af09d1b468-2121x1414-1.webp?w=2048
canonical_url: https://theswordblogsite.wordpress.com/2024/02/26/how-to-document-when-you-dont-like-documenting/
---

I don’t really like writing documentation, and I can count with half a hand, the number of engineers I’ve worked with that truly and honestly liked to do it. But, if there is something I dislike even more, is having to answer the same questions over and over about how to use my app or script.

Due to that (in your face positive motivation) I’ve spent some time learning a few tricks on how to create documents easy to read, and easy to write, with out having to spent much time on them, and I’m willing to share them with you.

## Set the Course Sailor

Just like when sailing in the middle of the sea, you need to know in which direction to point your boat. Or you could end up messing it up big, really big. When writing docs you need to know which is your target audience.

![](https://theswordblogsite.files.wordpress.com/2024/02/screenshot-2024-02-23-at-08.17.59.png?w=884)

Your **target audience** will define how technical you can get on your explanations, and will give you a better idea of how people will interact with your project. For instance, if you’re writing for developers, you may want to include more technical details and even some insight of internal design, and expect them to make a more advance usage of it. On the other hand, when writing for people how “doesn’t speak dev” ( like a marketing team), you’ll have to reduce the number of technical words and expect a more basic usage of it.

Do not try to… let me emphasize that, DO NOT try to create a document for both, technical and non-technical audience. It’ll be boring for technical folks, and confusing for non-technical ones. If you need to target both, create separated documents.

Once you know who’s gonna be reading your doc, its time to sit down and start writing.

## The IBM Pattern

No, this is not the “International Business Machines” pattern, its the **“Intro-Basic-More”** pattern, based on the [_KISS principle_](https://en.wikipedia.org/wiki/KISS_principle) (Keep It Simple, Sailor). What is that IBM thing? Is a simple mnemotechnic I use to remember that any documentation (like a README file) should have the following:

- An **Introduction** section, explaining what the tool/service/project is about. It has to be concise and brief. Don’t overthink it, one sentence or two at top, and that should be it. You can also include the (one-liner) _install_ command here.
- The **Basic Usage** section should show the users how to achieve the most probable reason why they want to use this tool/service/project, and only that. If you’re writing a doc for _grep_, the basic usage is `grep 'skywalker'`, if you’re writing a doc for _curl_, the basic usage is `curl starwars.com`. Give them what they came to find right away.
- Last but not least, **More Questions**. This section should present a way for the reader to find more information if the basic usage is not enough. It could be a list of FAQs<sup data-fn="5bc47ef8-27b8-4f14-930a-5c9d8ef5b7d3"><a href="#5bc47ef8-27b8-4f14-930a-5c9d8ef5b7d3" id="5bc47ef8-27b8-4f14-930a-5c9d8ef5b7d3-link">1</a></sup>, how to use the “help/usage” command, a link to a more detailed document (like a Swagger based site), or a way to contact you (not recommended).

By following this patter you’ll make sure that anyone who reads it will get a clear idea of what you project is for and what it does, how to make a basic usage of it, and how to get more info if needed.

## VHS

Some of you may say “Sounds great Santi, but how can I document the basic usage if I don’t like documenting”. Argh! What a predicament, but I got you covered.

There is this tool I’ve been using for **showing** users how use my scripts and apps, with little to no effort from my side. It’s called [VHS](https://github.com/charmbracelet/vhs?tab=readme-ov-file#vhs) (yes, as in **Video Home System** ) and it allows you to create GIFs of commands running on a terminal, from the terminal. Is not a recording app (tho it can do that as well), it’s a GIF generator.

You can instruct VHS to create a GIF running your app. And update that GIF automatically on every release. So you’ll get your documentation up to date effortlessly.

For instance, this is a script I wrote for dev teams to create a couple of Kubernetes manifest files. It has many options to customize those manifests, but for most common usage, which is a new app for development, this is more than enough:

![](https://theswordblogsite.files.wordpress.com/2024/02/add_app.gif?w=900)

## Get Your Own Boat

Let me show you how to use VHS by following the IBM pattern.

### VHS Intro

This tool allows you to create terminal GIFs as code for integration testing and demoing your CLI tools.

Install it by simply running: `brew install vhs`. Check for more install options [here](https://github.com/charmbracelet/vhs?tab=readme-ov-file#installation).

### Basic Usage

1. Create a new _vhs\_demo.tape_ file with the following content:

```
Output vhs_demo.gifRequire echoSet Shell "bash"Set FontSize 16Set Width 800Set Height 450Type "vhs vhs_demo.tape"Sleep 1sEnterSleep 5s
```

2. Change the “_Type_” command with your own.

3. Execute VHS to generate the GIF:

![](https://theswordblogsite.files.wordpress.com/2024/02/vhs_demo.gif?w=800)

4. Get the _vhs\_demo.gif_ file generated on the same folder.

### More Questions

Run `vhs -h` to see all the options available, or check [the official docs](https://github.com/charmbracelet/vhs?tab=readme-ov-file#vhs-command-reference) to learn more about VHS and its advance usage.

## Raise the Sails

Following this pattern, and using VHS for adding examples and expected outputs has helped me a lot to reduce the number of times people needs to come to me for help for common tasks. Hope it helps you too.  
  
What do you think about it? How do you write your docs? I really wanna know ![😀](https://s0.wp.com/wp-content/mu-plugins/wpcom-smileys/twemoji/2/72x72/1f600.png)

1. Frequently Asked Questions [![↩](https://s0.wp.com/wp-content/mu-plugins/wpcom-smileys/twemoji/2/72x72/21a9.png)︎](#5bc47ef8-27b8-4f14-930a-5c9d8ef5b7d3-link)