Rolfe Dlugy-Hegwer

Homebrew is a command line utility that makes installing software easier because it does a good job of installing any dependencies for you. Unfortunately, users sometimes run into trouble while installing Homebrew. Here, I show you how to perform the “default” installation that Homebrew recommends on the home page of its website.

Open Terminal and confirm that Homebrew is not installed by running the brew --version command. If it isn’t installed, the output returns Command 'brew' not found. For example.

username@laptop:~$ brew --version

Command 'brew' not found.

Visit the Homebrew website, https://brew.sh/, and copy the installation command by clicking the copy icon:

In Terminal, paste the command by pressing the Ctrl+Shift+V keys at the same time. Then, press Enter to run the command.

$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

You must install Git before installing Homebrew. See:
  https://docs.brew.sh/Installation

username@laptop:~$ git

Command 'git' not found, but can be installed with:

sudo apt install git

If your system doesn’t have git, the output prompts you to install it. So you do that.

$ sudo apt install git
[sudo] password for username:        
Reading package lists... Done
Building dependency tree       
[...]
Processing triggers for man-db (2.9.1-1) ...

Note: Whenever prompted, enter y to continue the installation process.

Note: I use [...] to indicate that I’ve omitted many lines of output.

Rerun the command that installs Homebrew. You can get the command back by pressing the up arrow key a couple of times until the command reappears.

$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
[...]

This automated installation process can take several minutes. When it finishes, the installer suggests “next steps” for you to complete the installation:

[...]
==> Next steps:
- Run these two commands in your terminal to add Homebrew to your PATH:
    echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"' >> /home/<username>/.profile
    eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"
- Install Homebrew's dependencies if you have sudo access:
    sudo apt-get install build-essential
  For more information, see:
    https://docs.brew.sh/Homebrew-on-Linux
- We recommend that you install GCC:
    brew install gcc
- Run brew help to get started
- Further documentation:
    https://docs.brew.sh

Copy/paste these next steps to a file in a text editor so that you can paste and run the commands one at a time.

As noted in the “Next steps,” add Homebrew to your PATH:

$ echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"' >> /home/<username>/.profile

$ eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"

As noted in the “Next steps,” if you have sudo access, install Homebrew’s dependencies:

$ sudo apt-get install build-essential
[sudo] password for <username>:        
Reading package lists... Done
[...]

Reload your terminal by closing and reopening the Terminal or by entering:

$ bash --login.

As noted in the “Next steps,” install the gcc compiler, which brew often uses:

$ brew install gcc
[...]

If the preceding brew command produces a Command 'brew' not found message, reboot your Linux system and try it again.

Congratulations! Using brew to install gcc or any other software verifies that brew is correctly installed and works!

Mermaid is a Javascript-based diagramming and charting tool that uses Markdown-inspired text definitions and a renderer to create and modify complex diagrams. The main purpose of Mermaid is to help documentation catch up with development.

https://github.com/mermaid-js/mermaid

In my recent interview with Tim Bannister, Tim encouraged contributors to create more diagrams for the Kubernetes docs based on the new diagram guide that chrismetz09 created in December 2021.

Notably, this guide shows how to code diagrams using mermaid.js in a live editor!

This notion of diagrams-as-code has tremendous appeal for me! To illustrate why, let me tell you a quick story.

A few years back, I enlisted the help of THE primary graphic designer where I worked to create an information-rich diagram for some product documentation. Because of her talent and organization’s size, she was very much in demand. Using specialized tools, she designed a beautiful and informative diagram and exported it to a graphics file, which I published. A few weeks after publication, the software engineering team made a software change, and just like that, the diagram became outdated!

That approach was much better than the ad-hoc approach that had preceded. At least now, our diagrams were expertly designed, correctly branded, and consistent across all our products.

Unfortunately, that new approach could not be scaled up to meet the customer demand for properly-illustrated documentation, which I estimate at a minimum of 5000 new or updated diagrams per year. I arrived at this figure by estimating ten-plus diagrams per product, times fifty-plus products, times ten-plus additions/updates per product per year. (10+ x 50+ x 10+ = 5000+)

With that backdrop, the benefits of having diagrams-as-code seem significant:

• Unlimited contributors can create and maintain diagrams using free and open-source software.
• Teams can store and manage the code for diagrams alongside the documentation source.
• The tooling separates content from presentation to give all diagrams a consistent look and feel.

Moreover, having source code for diagrams makes it is easier to search for specific terms when updating diagrams and conducting peer reviews.

I think it would make sense to give this new approach a try.