Many simple tools, loosely coupled

Our approach to technology here at the OERu is inspired by the UNIX tool philosophy which can be summarised as follows:

"create simple tools that do one job well, and make it easy to combine them to work together"

In the UNIX (and, somewhat more recently, the Linux) computing environment, this originally meant a lot of small commandline applications like "ls" for listing the contents of file directories, and "grep" for searching directories of files for words and other snippets of content, and "diff" for showing the difference between two files, and many many more. These all output text, and they also accept text as an input - you can chain all of these simple little applications together to create, on the fly, remarkably complex capabilities. This is one of the things that makes Linux and the commandline so powerful for those who have learned its lore (and so intimidating for those who haven't yet done so). 

This idea of "loosely coupled" tools, working together is also a good way to describe both the OERu technology and documentation philosophy.

On this website, the way it manifests is interesting - each time I write a howto article, there're certain common tasks - things like setting up Docker, or creating secure SSL certificates for encrypting user interactions with a web service.

Initially, I wrote howtos with all of those details contained in one document, however the instructions fairly quickly become outdated, for example, the install process for Docker or Let's Encrypt is changed by its community (usually to make it faster and more convenient) or to reflect the release of new software dependencies. It doesn't sit well with me to be leaving outdated or inaccurate resources on the web - I feel a responsibility for curating them to improve the signal-to-noise ratio of the 'net. Also, it rapidly becomes an intractable problem to go through old howtos to update all the slight variations on the same instructions to something new (the problem grows exponentially as more howtos are added).

So, taking the UNIX approach, I use my experience writing a few howtos to provide insight into parts of each that are repeated. Any section repeated (more or less unchanged) in each howto is a candidate for replacement with a stand-alone howto.

As it turns out, the community that's building the Docker container technology has done a good job of keeping their installation documentation up-to-date and making it easy to find the relevant info for our target platforms, Ubuntu Linux 14.04 and 16.04. As a result, there's no point in my repeating their instructions. Instead, I just point my readers there when it's time to install Docker.

My first candidate for documentation "refactoring" was the "Let's Encrypt" SSL Certificate process (it's a feature of almost all my howtos to date). Having now created that stand-alone howto, I can replace the largely repeated sections of several howtos with a single link to the same place.

Yes, this change adds the overhead of the reader of a howto needing to go to a different article on this site, but I think this is greatly outweighed by the benefits: if I need to update or improve the description of this operation, I can simply update one document and ensure it's got the "best of" tips across all the different howtos. Also, if people leave questions or comments, all relevant ones will be in the same place, making it easier for other site visitors to find them.