Coding

Introduction


With the ubiquity of information technologies, understanding basic coding principles is essential for technical communicators. While the coding skillsets of most technical communicators need not be on par with those of web and application developers, building literacies in programming and markup languages enables Technical Communicators to be in conversation with web and software developers on their teams. Research has shown that deep knowledge of any one particular tool, technology, or coding language isn’t always necessary for technical communication practitioners, but that adaptability and an ability to learn new technologies benefit technical communicators in their job search [1].


Some languages are particularly suited to writing APIs (Application Programming Interfaces), which is a set of rules and protocols that determine how a particular piece of software works in a given environment [2]. Other languages are better suited to organizing and structuring information, while others are used to analyze and store data. Some other languages form the basis of operating systems, while still others are used for web, game, and other application development.


In this article, the term "coding" encompasses both programming languages and markup languages. This article highlights languages that are important for Technical Communicators but does not provide a comprehensive list of programming and markup languages.



Overview

What's the difference between Markup Languages and Programming Languages?

Markup languages are distinct from programming languages in that their purpose is to annotate and describe data. Programming languages, on the other hand, include a robust set of commands and instructions that are used together to create a software program [3].


High-Level and Low-Level Programming Languages

The delineation between high and low-level languages is based on the language's relative level of abstraction, a term common in computer science that describes the degree of separation the language has from the machine's (commonly a computer's) own internal logic [4].


High-Level

Higher-level languages, such as Java, PHP and Perl are said to have a high level of abstraction and are written with English-like terminology that people can understand [5]. High-level languages must be translated into machine code before the program can be executed and are thus slower than their low-level counterparts, a trade-off for their relative ease of use [6].


Programmers use high-level programming languages to write software programs.


Low-Level

Low-level languages, such as machine and assembly code, on the other hand, deal directly with the hardware components of the system. Machine code is commonly referred to as binary (1s and 0s). Low-level languages are very efficient in terms of their memory use and are executed faster than their high-level counterparts [7].


Machine Language. Source: Wikipedia user Turkei89, 2012Creative Commons Attribution-Share Alike 3.0 Unported license.

Finally, the distinction between high and low-level programming languages is more of a spectrum than a strict either/or. For example, languages such as C and C++ might be seen as more mid-level languages as they're abstracted from machine code, but not as much as other higher-level languages and are still rather fast and efficient in their use of memory [8].


Markup Languages and Front-End Web Development

XML

XML stands for eXtensible Markup Language and is a way to structure content by using tags, which can be considered labels that describe the content presented. On its own, XML does nothing except describe the data on the page [9]. One of the distinguishing features of XML is that the language allows users to create their own tags, allowing for customizable and specific content tags [10]. This allows users to search XML documents by these specific tags. Documents written in XML can be searched with specific software to retrieve data [11]. Because specific sections and data can be accessed this way, XML allows for content reuse. Data authored in XML can be considered modular, in that it can be separated from the whole or combined with other data to form a new document.

In order to function properly, XML documents must adhere to certain rules. First, XML documents must be well-formed, which means that they must follow all of the formatting specifications of the language [12]. Secondly, XML files must also be valid. An XML document is considered valid if the markup in the document matches the set of rules defined in the document’s DTD (Document Type Declaration) or schema [13].


A recipe written in XML. SVG rendering of the basic RecipeBook example from <http://www.happy-monkey.net/recipebook/doc/author-tutorial.html>, with added XML declaration and DTD information.Original example by David Horton, SVG rendering by wikipedia User:Andrew_pmk.Original work licensed under CC-BY-SA-2.5| SVG rendering licensed under CC-BY-SA-2.5


HTML


HTML stands for Hyper Text Markup Language and is the standard markup language in which web pages are written [14]. HTML has been described as similar to typesetting in traditional print media, such as newspapers, books, etc. [15], as it allows the user to organize and structure the content of webpages, [16] by tagging content. Unlike the tags in XML, which can be customized on a case-by-case basis, HTML uses a set of predefined tags that determine the organization, spacing, and structure of the text and images that make up web content. For example, HTML tags tell the web browser “this piece of content is an image,” “this is a list,” or “this is a paragraph” [17]. One of the most defining characteristics of HTML is that the language allows you to link from one web page to another [18].


HTML was designed to allow both humans and machines to be able to quickly understand the information structure of the content [19].


Using HTML tags correctly is an integral part of making web content more accessible for users that rely on adaptive technologies to access the internet [20]. For example, HTML’s built-in heading tags (H1, H2, H3, H4, H5, H6) not only provide a visual hierarchy with which to organize content but also enable quicker navigation for those who rely on keyboard navigation, rather than a mouse, to control their computer [21].

<!DOCTYPE html>

<html>

<body>

<h1>Heading 1</h1>

<h2>Heading 2</h2>

<h3>Heading 3</h3>

<h4>Heading 4</h4>

<h5>Heading 5</h5>

<h6>Heading 6</h6>

</body>

</html>

Simple HTML code that uses tags that define the structure of an HTML document. Source: Philips, J. 2021
Note that tags in HTML have a beginning tag <h1> and closing tag </h1>, but that the tags do not appear when rendered
A rendering of the above HTML code in a web browser. Source: Philips, J., 2021

CSS


CSS stands for Cascading Stylesheet. While HTML organizes the content and structure of web pages, CSS is a markup language that defines how the content will be displayed by the browser, determining the color, font family and size, position on the page, among other factors [22]. CSS does this without impacting the organizational structure or meaning of an HTML file [23].


CSS is often described as a set of rules that define how certain parts of HTML files will be displayed [24]. CSS rules can be specified within an HTML document, though referencing (linking) to an external CSS file is considered best practice, as it allows the user to use the same style sheet for multiple HTML files, which is more efficient and also ensures design unity across the website.




body {

background-color: lightskyblue;

}


h1 {

color: papayawhip;

text-align: center;

font-family: cursive;

padding: 100px;

}


h2 {

color: purple;

}


h3{

color: darkcyan;

font-family: sans-serif;

padding: 100px;

A snippet of CSS code. Source: Philips, J. 2021
When this CSS is applied to the HTML code presented above, the HTML looks like this in a web browser:
Simple HTML styled with CSS. Source: Philips, J., 2021

JavaScript


JavaScript is a programming language widely used to control web pages and make them interactive [25], [26]. For example, JavaScript is used to make web pages change in response to a specific event, such as the user clicking on a button. JavaScript can be used to trigger pop-up windows, display dropdown menus, and validate forms [27]. Like CSS, JavaScript can be written in an HTML file, or referenced (linked to) in an external file [28].


Due to the similarity in their names, JavaScript is commonly confused with Java. However, JavaScript is a distinct language that can only be run on web browsers and cannot be used to create standalone applications, like Java [29]. Another key difference between the two languages is that JavaScript is an entirely text-based language and does not need to be compiled (transformed) before programs written in JavaScript can be run, like Java [30].

On a mobile device or small screen, the following snippet of JavaScript code is what tells the website to expand the drop-down menu:

on('click', '.mobile-nav-toggle', function(e) {

select('body').classList.toggle('mobile-nav-active')

this.classList.toggle('bi-list')

this.classList.toggle('bi-x')

})

Simple JavaScript code. Source: Philips, J., 2021

When the three horizontal lines in the right-hand corner of the toolbar (below) are clicked, the toolbar expands, changing from this:
Collapsed toolbar on a mobile or small screen. Source: Philips, J., 2021

To this:

Expanded toolbar on a mobile or small screen. Source: Philips, J., 2021

Programming Languages

C

C is a lower-level programming language that exists a level above the machine code. Because C, like many low-level languages, uses memory efficiently, it is ubiquitous in the programming world and is present in most computer operating systems. C is also used to write in operating systems found in medical devices and video game hardware [31].

C was originally developed in 1972 and is sometimes referred to as the "mother of all programming languages".


#include <stdio.h>


int main() {

printf("Hello World!");

return 0;

}

Hello World in C. Hello World is commonly one of the first programs developers write when learning a new language. This simple program simply says "Hello World" to the user. Source: Philips, J., 2021

References


  1. Brumberger, E., & Lauer, C. (2015). The Evolution of Technical Communication: An Analysis of Industry Job Postings. Technical Communication, 62(4), 224–243.

  2. Christensson, P. (2016, June 20). API Definition. Retrieved 2021, Oct 27, from https://techterms.com

  3. Christensson, P. (2011, September 23). Programming Language Definition. Retrieved 2021, Oct 27, from https://techterms.com

  4. Siddiqi. (2020, July 20). Understanding high and low level languages. CodersLegacy. Retrieved November 12, 2021, from https://coderslegacy.com/high-level-and-low-level-languages/.

  5. Siddiqi. (2020, July 20). Understanding high and low level languages. CodersLegacy. Retrieved November 12, 2021, from https://coderslegacy.com/high-level-and-low-level-languages/.

  6. Siddiqi. (2020, July 20). Understanding high and low level languages. CodersLegacy. Retrieved November 12, 2021, from https://coderslegacy.com/high-level-and-low-level-languages/.

  7. Siddiqi. (2020, July 20). Understanding high and low level languages. CodersLegacy. Retrieved November 12, 2021, from https://coderslegacy.com/high-level-and-low-level-languages/.

  8. Siddiqi. (2020, July 20). Understanding high and low level languages. CodersLegacy. Retrieved November 12, 2021, from https://coderslegacy.com/high-level-and-low-level-languages/

  9. W3Schools. (n.d.). Introduction to XML. XML Introduction. (n.d.). Retrieved November 12, 2021, from https://www.w3schools.com/xml/xml_whatis.asp.

  10. Applen, J. D., McDaniel, R., Applen, J. D., & McDaniel, R. (2009). Introduction to XML: A Primer on the eXtensible Markup Language. In The rhetorical nature of XML: Constructing Knowlegde in Networked Environments (pp. 41–94). essay, Routledge.

  11. Applen, J. D., McDaniel, R., Applen, J. D., & McDaniel, R. (2009). Introduction to XML: A Primer on the eXtensible Markup Language. In The rhetorical nature of XML: Constructing Knowlegde in Networked Environments (pp. 41–94). essay, Routledge.

  12. Battalio, J. T. (2002). Extensible markup language: How might it alter the software documentation process and the role of the Technical Communicator? Journal of Technical Writing and Communication, 32(3), 209–244. https://doi.org/10.2190/bdf0-uccp-y5m5-bblb

  13. Battalio, J. T. (2002). Extensible markup language: How might it alter the software documentation process and the role of the Technical Communicator? Journal of Technical Writing and Communication, 32(3), 209–244. https://doi.org/10.2190/bdf0-uccp-y5m5-bblb

  14. W3Schools. (n.d.). HTML Tutorial. HTML tutorial. Retrieved November 12, 2021, from https://www.w3schools.com/html/default.asp.

  15. Applen, J. D., McDaniel, R., Applen, J. D., & McDaniel, R. (2009). Introduction to XML: A Primer on the eXtensible Markup Language. In The rhetorical nature of XML: Constructing Knowlegde in Networked Environments (pp. 41–94). essay, Routledge.

  16. W3Schools. (n.d.). HTML Tutorial. HTML tutorial. Retrieved November 12, 2021, from https://www.w3schools.com/html/default.asp.

  17. W3Schools. (n.d.). HTML Tutorial. HTML tutorial. Retrieved November 12, 2021, from https://www.w3schools.com/html/default.asp.

  18. Applen, J. D., McDaniel, R., Applen, J. D., & McDaniel, R. (2009). Introduction to XML: A Primer on the eXtensible Markup Language. In The rhetorical nature of XML: Constructing Knowledge in Networked Environments (pp. 41–94). essay, Routledge.

  19. WebAIM. (2020). Semantic structure: Regions, headings, and lists. WebAIM. Retrieved November 12, 2021, from https://webaim.org/techniques/semanticstructure/.

  20. WebAIM. (2021). Skip navigation links. WebAIM. Retrieved November 12, 2021, from https://webaim.org/techniques/skipnav/#headings.

  21. WebAIM. (2021). Skip navigation links. WebAIM. Retrieved November 12, 2021, from https://webaim.org/techniques/skipnav/#headings.

  22. W3Schools. (n.d.). CSS Introduction. CSS introduction. Retrieved November 14, 2021, from https://www.w3schools.com/css/css_intro.asp.

  23. WebAIM. (2020). Semantic structure: Regions, headings, and lists. WebAIM. Retrieved November 12, 2021, from https://webaim.org/techniques/semanticstructure/.

  24. Larsen, R., & Larsen, R. (2013). Cascading Style Sheets. In Beginning HTML & CSS (pp. 191–255). essay, J. Wiley & Sons.

  25. Christensson, P. (2014, August 8). JavaScript Definition. Retrieved 2021, Nov 14, from https://techterms.com

  26. Mozilla. (n.d.). About JavaScript - JavaScript: MDN. JavaScript | MDN. Retrieved November 14, 2021, from https://developer.mozilla.org/en-US/docs/Web/JavaScript/About_JavaScript.

  27. Mozilla. (n.d.). About JavaScript - JavaScript: MDN. JavaScript | MDN. Retrieved November 14, 2021, from https://developer.mozilla.org/en-US/docs/Web/JavaScript/About_JavaScript.

  28. Christensson, P. (2014, August 8). JavaScript Definition. Retrieved 2021, Nov 14, from https://techterms.com

  29. Java. (n.d.). How is JavaScript different from Java? Java.com. Retrieved November 17, 2021, from https://www.java.com/en/download/help/java_javascript.html#:~:text=Key%20differences%20between%20Java%20and,code%20are%20all%20in%20text.

  30. Christensson, P. (2014, August 8). JavaScript Definition. Retrieved 2021, Nov 14, from https://techterms.com

  31. Philips, J. (2021, September 24). Increasing computer security in C. Increasing Computer Security in C | Portland State University. Retrieved November 18, 2021, from https://www.pdx.edu/research/news/increasing-computer-security-c.

Last updated by Judy Philips on November 18, 2021