Degrees of Transparency

So far, we’ve covered three broad areas related to open software.

First, the development of software that we might choose to employ in our research. We’ve discussed the fact that Open Source and Free Software differ from closed source software in that the code behind the program of the former can be accessed by anyone with the knowledge to interpret it. This is one level of transparency in the larger digital ecosystem in which we work.

Second, we’ve touched on how we might shift the paradigm of a piece of software or code that tells the computer what to do, to one where it tells the human reader of the code what the computer should be doing. In this way, literate programming tries to wed together one’s inputs (data) and one’s outputs (manuscript). This adds a further level of reproducibility.

And finally we’ve talked about clearly communicating what our code is trying to do, enhancing transparency through legibility.

We can also take this discussion down a slightly different avenue and introduce the impact of user interface on the transparency and reproducibility of the various aspects of our research.

So let’s talk about WYSIWYGs for a moment.

WYSIWIG vs Markup & Scripted Language

An important differentiation when we talk about software that supports open research and transparency is the difference between WYSIWYG (What You See Is What You Get) software — which may well be open source and even adhere to the ethos of Free Software — and software that requires the user to explicitly markup what they’re doing — generally both human and machine readable, to a degree. We’ve already introduced aspects of this when talking about literate programming.

You may also hear or read the acronym GUI – GUI stands for Graphical User Interface. This is very much synonymous with What You See Is What You Get; the GUI allows us to undertake actions without explicitly marking up or writing out what we want to do — whether that’s saving a document, setting text to bold, or transforming our data. Day to day, all of us engage with GUIs, from tapping our phones to using Microsoft Word! But a bit more on the implications of this for research…

Structure and Content

Openness in a computing environment will always be intrinsically limited — when a program is compiled (turned into a series of 0s and 1s representing computer operations) the resulting product is indecipherable to a human. That being said, if any document is going to pass the test of time in a computing environment, it is a plain text file. The issue with plain text files is that they convey only words — all structure (things like pagination, headings etc) and semantics (word meaning and / or emphasis) are not built-in characteristics. Structure and semantics are an added layer, and bring meaning to the reader.

This might be why we like things like Microsoft Word so much — the program allows us to easily see our document structure and encourages a sense of semantics — through the use of bolding, italics, colour, titling and pagination we construct our prose and our document structure at the same time. The catch is that our prose (content) and structure are embedded in a particular program. This has two knock-on effects. First, lose the program and you lose your prose. Second, you lose the ability to view your content independent of its structure and risk obscuring content behind structure.

Markup, or Markdown — a markup implementation — attempts to resolve this by separating out document structure and document content. Some markup languages integrate significant levels of semantic integration, while others are more focused purely on structure. R Markdown, which we’ve already encountered, is one implementation of markdown. Another popular option in certain disciplines that you may have come across is LaTex. HTML, a markup language, provides the underlying structure to the webpage that you are viewing right now in a plain text environment; your web browser renders the content in a pretty way. If you want to see the underbelly of this web, or any webpage, you can right click on your mouse right now and select the option that reads something like “View Page Source”.

What all of these iterations of the ‘markup’ model have in common is that they rely on a second program to translate the markings in the document to visual, interpretable content for human digestion — look back at the R Markdown document and corresponding pdf on the previous page to see this translation in action. What they also have in common is an underlying plain text document that can be read on virtually any computer from the inception of the computer and that will still be readable by both a computer and a human for decades to come.

If you’ve used a wiki editor, you’ve used markdown. And wikis can be a great way to introduce students to practices in open sharing of knowledge created through a transparent, text based tool, that allows for greater portability and adaptability than what we would find in a WYSIWYG editor.

Let’s briefly recap.

  • WYSIWYGs give you a graphical interface (GUI) where your content and your structure cannot be separated – they provide a document with pagination and the ability to change fonts, bolding, colours etc. on the fly with the click of a button.
  • Markup, or markdown, employs a three step process. In a plain text editor, you write, without distraction from the ability to change your formatting. When you’re done, you call on another program to transform your text into a Word document, pdf, PowerPoint etc. To view the formatted document, you open it with a third program — your web browser, pdf reader, or word processor.

Dig Deeper

  • Check out some basic markdown syntax with this markdown guide.
  • Explore the CSS Zen Garden to see examples of the power of separating structure and content. All of the example web pages display the same content (from the html file), but with wildly different formatting (from the various Cascading Style Sheet (CSS) files).
  • Check out the Additional Open Software page for help in selecting a markdown editor in which to start composing beautiful text-based documents.

Going Up the ladder

At this stage, we’ve touched on the applications that support one’s work. These applications all reside within a larger ecosystem, an operating system.

Operating systems exist in a similar environment to that described in our discussion about closed source, open source, and free software. Your choice of operating system will impact your choice of applications to pursue your research, how interoperable these programs are (and by virtue, the content that you build in them), and how transparent and reproducible you can make your work.

Windows OS is entirely closed source. Mac OS is closed source, but because of its underlying structure it is compatible with many tools and scripts built for Linux. Linux is open source and distributions are often driven by the GNU philosophy of Free Software. As you will have experienced, some software is only available for specific operating systems (e.g. Windows only). If you’re going to be collaborating with others in your field it’s a good idea to ask around and see what systems others are using. In a later section we’ll also discuss containers, which can greatly help in collaboratively developing software with people who use different operating systems.

Dig Deeper