The following describes the best tools for SOIL module development and how we arrived at our conclusions. Like all SOIL content these conclusions may change over time.

If you are looking to just get started and need a guide for setting these up consider the starter module VuePress SOIL on Netlify.


The Apple Mac user interface has long been preferred by writers, educators, and designers for a reason. It is snappy, efficient, and extremely well thought-out. It is also much more expensive. Here are some specifics that currently no other operating system does as quickly and clearly:

  • spotlight searching,
  • screenshots,
  • video capture,
  • audio recording,
  • window navigation,
  • emoji integration,
  • full UNICODE support,
  • multiple screen support, and
  • POSIX and UTF-8 bash command line terminal.

Some of these might seem trivial but they really add up when creating interactive learning content as SOIL promotes.

The last one, bash command line integration, has been a distinguishing advantage for more than a decade and perhaps the main reason developers—particularly web developers—overwhelmingly choose Mac as their operating system of choice. Since SOIL content is mostly just web content in its simplest form it follows that a Mac is best suited to create it.

That said, Windows has made tremendous strides on this front. Visual Studio Code has leveled the playing field in some sense because it provides a rich terminal command line when Git-SCM is installed. Still it has to be installed and configured correctly, which is simple enough but unnecessary if you have a Mac or Linux machine.

Linux, of course, is always an option for the technically inclined. Our conclusions are made assuming the least technical content creator possible. Using Linux—even just as a desktop OS—requires considerably more technical skill.


This is largely a personal choice. They all claim they are faster more private, and have better battery life than the others, but provide little or no data to back up their claims. Try them and make your own choice.

  • Currently Google Chrome is—without dispute—the world's leading web browser both in terms of adoption and content development. It is also most likely to best integrate with your Google ecosystem of tools.

  • However, the new Firefox is a serious alternative as well. Firefox comes with better privacy considerations and tracking blocks.

  • Microsoft Edge will work but has far fewer developer tools than either Chrome or Firefox making it good for browsing but insufficient for any web development. If you are not planning on doing any technical web development this should not be a problem.

Every other browser—including Safari and Brave—is considerably far behind the others. Use one of the three above to avoid complications later.


Visual Studio Code is quickly becoming the world's standard visual editor both for code and technical documentation for the following reasons:

  • 100% open source with no lurking proprietary gotchas,
  • full support on all major operating systems (Mac, Windows, Linux),
  • designed like other light-weight editors (Sublime, Atom, Brackets),
  • faster than most other light-weight editors,
  • based on Electron web technology,
  • supported by (the new) Microsoft,
  • no fuss Git and GitHub integration,
  • Live Share extension making it Google docs for coders,
  • Settings Sync extension for all your computers,
  • vim bindings for ops programmers who prefer,
  • powerful command line terminal support,
  • instance color and theme changes,
  • extensive community of developers and extension writers.

You may be tempted to use a proprietary tool like Microsoft Word, Google Docs, or Typora but resist. VSCode, when paired with a great renderer, provides more than than any stand-alone editor ever can by allowing you to preview in your browser exactly how your content and app will appear to users.


Currently nothing beats VuePress for turning your content immediately into a progressive web application allowing it to be used offline as an app on any device that supports PWAs.

VuePress is amazingly good at displaying your changes immediately in the web browser in real-time as you edit your content eliminating the need for any built-in rendering an editor app might offer.

Why use a pretend preview when you can preview the real thing?

Here is an image of the Visual Studio Code editor in the left Window with Chrome in the right showing the changes as they happen.

While there is a plethora of static site generators to choose from as renderers these days—all designed for JAMstack development—none have anywhere near the minimal approach that VuePress starts with out of the box. VuePress is dramatically better than all the rest—including Gatsby—for the type of sustainable content development SOIL promotes.


Currently the easiest tool to use with Git is the editor Visual Studio Code.

While it is true that Git has a powerful command line interface most of this complexity is hidden behind a simple graphic user interface allowing anyone to use it easily.

Here's an image of a git diff shown with the graphic user interface instead of requiring the command line.


Hosting refers both to knowledge source code as well as the rendered content. Choosing a good hosting provider makes your content open and sustainable. The best hosting providers are free, allow content to have a name, support automatic rendering, have millions of active users, be open but have support from large companies, have a substantial content delivery network, enable integration with other services.


GitHub is the overwhelming leader when it comes to get Source management and hosting. In July 2018 GitHub was purchased for 7.5 billion dollars by Microsoft. It has millions of users and hosts billions of lines of content.


Although GitHub provides site rendering Netlify provides better site rendering with more options, a larger CDN, and the ability to pull source from different hosting providers including your own private git repository if you choose to host your own instead of using a service like GitHub. This provides a great amount of flexibility as to where and how you host your source content. if you change your mind later and decide to host your content elsewhere Netlify can remain your site rendering service. Such flexibility--if it maintains simplicity--provides the sustainability required by the soil standard.

Netlify now also provides custom domain name hosting and management which simply means you can give your site a name to which others can reliably refer.


A shell is the program that is run on your command line terminal to provide interaction with the command line.

The most important criterion when selecting a shell is ubiquity. The POSIX shell standard has widely been accepted since the 1970s. The most ubiquitous and acceptable shell that implements this standard is Bash. Bash has been the default shell on Unix and Linux systems for more than two decades and the default on Apple Macintosh computers for more than a decade.

In 2017 Windows began experimenting with Bash support but thankfully has full support for Bash through which Visual Studio Code seems to prefer for Git integration, one main reason to use Visual Studio Code in the first place.

You don't have to become a shell master to create content but basic mastery of the following commands is required:

mkdir repos
cd repos
git clone <repo>
cd <repodir>
code .

Knowing how to stop running shell commands with <control-c> is also useful.

Learning more about the shell later will serve you well.


Capturing a screenshot or screencast is a fundamental skill for developing any SOIL content. The tools differ widely based on operating system.


The built in <cmd>-<shift>-4 allows you to capture a section of your screen.

⚠️ Do not use the <space> option to capture a window on Mac because it automatically surrounds your capture with a drop shadow that can cause problems.

The free Skitch app from Evernote is useful for annotating and editing screenshots. The blur and arrow tools are particularly useful.

Last Updated: 10/3/2018, 6:48:43 PM