Chapter 1: Tutorials
This section defines technical communication and tutorials and explains why you should use this tutorial as you write your own.
What is technical communication?
Technical communication is writing that presents need-to-know, accurate, complex information to specific audiences clearly and concisely in well-designed deliverables, known as document genres, such as tutorials, proposals, and reports. Technical writing is characterized by “precision and intent” since all information must be correct (Laplante, 2024), readable, and usable.
Technical communicators translate data, information, and existing company texts into different genres, created in different modalities and formats, while using different technologies as information designers (Hart-Davidson, 2013).
This means that technical communicators are tasked with talking to subject matter experts, interpreting data in visual and written texts, developing deliverables that align with user expectations and company branding while using technologies to ensure development of ethical, concise, clear, and useable documents.
What is a tutorial?
Tutorials, also known as documentation in the software industry, are a genre of technical communication that describes, defines, and instructs how to use an object and complete actions. Tutorials can be short, such as a Quick Start brochure, or longer, such as a 1000-page documentation that explains how to use a complex software program.
The purpose of all tutorials is to inform, but some do persuade. All tutorials include explanations of the product including what the purpose is, who it is for, and how to use it. Some tutorials also try to persuade the audience to buy or use the product, such as in a Guided Tour and Demonstrations (Barker, 2012).
Tutorials can be written for audiences ranging from beginners to experts, but they need to be organized with easier information first progressing to more difficult since the underlying assumption is that the audience will gain “skill[s] and confidence” (Barker, 2012, p. 30) as they work through the tutorial. Even computer engineers and software developers use tutorials during the software development cycle (Hu, 2012), which means that tutorials are necessary for both front and back-end users.
Biggest issues in documentation
According to research, the biggest issues with some software documentation is a lack of clarity, accessibility, and usefulness, and it is up to technical communicators to practice correctness, completeness, and currency in their documentation writing (Aghajani et al., 2020; Imani et al., 2024). This means that tutorials need to be written with plain language, clear navigation, accuracy, and complete up to date information. Additionally, the most important element of tutorials is their usability since if users cannot “perform a task quickly and efficiently” then the document is “ineffective” (Alexander, 2013, p. 237), which creates significant issues for users as well as the company or client for which the document was written.
Cross-functional teams
Most documentation is written iteratively while the team is working on the software in a cross-functional team scrum agile workflow, which is highly dynamic and includes constant team communication and responsiveness to changes in the team, software, and work production (Carneiro et al., 2018). Although such a workflow is vital in industry, and you will learn more about agile, waterfall, and traditional in other classes, this class won’t address project management concepts, but you do need to know that documentation is not normally written by a single person without a team.
Who is this tutorial for?
This document is a tutorial explaining how to write a tutorial for technical communication, computer science, and information technology students. Some experts believe that understanding and practicing technical writing is imperative for these students, especially if they intend to work in the software industry (Laplante, 2024), and UCF concurs.
Since “software documentation is also a means … to manage and communicate [during the] software development process” (Hu, 2012), students must learn how to write them before entering the industry.
Although you should have some foundational knowledge of technical communication before writing a lengthy tutorial, this document will provide enough information to help you be successful as it contains information about the technical writing process, tutorial PDF and website organization and content, writing style, and document design. Although this document is specifically about tutorials and documentation, all concepts discussed apply to technical communication as a whole, meaning, for example, the design principles of grouping, contrast, alignment, balance, and consistency should be illustrated in any technical document and genre.
How can this tutorial help you?
This document intends to provide you road map to follow as you write your own tutorial; however, you do NOT need to follow the design of this document, and since this tutorial is not focused on a software application, the content and organization will be vastly different than the tutorial that you will write. Hopefully, however, this tutorial will help you to understand how to write and design your own documentation.
Ultimately, your tutorial needs to include content and design elements that YOUR specific audience needs and expects. This document, for example, is written for you as a student who is learning how to write and design software documentation, so the design and language choices are accessible to you as a college student. In fact, for jargon, or new vocabulary, a glossary is included in the back matter section of this tutorial.
You should not read this tutorial like a book from cover to cover; instead, use the menu to find the section you need when you need it. Since all elements of this tutorial are equally important and may be needed at the same time, you will probably need to skip from section to section to find information that you need as you write. For example, as you write your introduction, you will also need to review the Writing Style section as well as the Technical Writing Process section. Additionally, design is just as important as content (Redish, 2012), so you will need to write and design at the same time while referencing multiple sections of this tutorial simultaneously.
What are the ethical considerations for technical communication that you should be aware of?
As a technical communicator, you need to consider several ethical issues since what you write in industry will affect users and the company that you represent. Ethics is a moral code of conduct that should be followed at all times in your behavior and writing.
According to Scott (2013), “technical communicators … need to know not only how to identify relevant [ethical] principles and laws to consider but also how to position themselves in relations of power across communicative situations, engage with other stakeholders in an open search for the best course, and negotiate competing perspectives and obligations to arrive at a commitment to action” (p. 213). This means that you not only need to understand your organization’s policies, laws, and constitutional rights, but also how to interact with others, present information accurately, and behave appropriately.
Ethics is not black or white, however, which is one reason why it is so highly debated. Ethics does not take place in a vacuum because people and situations are complex. People have varying perspectives on what is accurate and true, and language is not always as precise as we would like. Additionally, ethics “must be continually, consciously considered, weighted, and acted upon” (Dombrowski, 2013). As a technical writer, you need to think about the context of your content, purpose of your document, intended audience, and company standards as you craft your words.
The Society for Technical Communication, which is a well-respected technical communication organization, lists 6 different ethical considerations for all technical writers, and most corporations and organizations have their own list of ethical practices, so make sure you research your future industry or the company for which you want to work, but here is a quick breakdown of technical communication ethics that you must follow:
Accuracy and Honesty
You will use data in your documents supplied by subject matter experts or gathered by you. This data must at all times be accurate and you must be honest in your interpretation, display, and presentation of that data.
For example, if you design a bar chart of numerical data, you must make sure that the data is correct, and the user will easily understand what that data means.
You cannot skew data to unfairly bias, falsify, or otherwise misrepresent part or all of the data.
The use of AI or source material must be accurately cited and used properly avoiding plagiarism.
Modifying and editing images is acceptable as long as you cite the original source, modify to include part of a graphic as long as you don’t change the essential meaning of it, and present the data truthfully and unbiasedly.
Professional Behavior
Technical communicators rarely, if ever, work alone as they are part of a cross-functional team that include company employees from different departments such as engineering, management, sales, marketing, etc. When you represent an industry, company, department, and team, you need to be professional in the way you speak, write, collaborate, and interact with others, including clients. It is up to you to always “do the right thing,” make appropriate decisions, write clearly, gather accurate data, and present information and images clearly and correctly.
Professional behavior includes maintaining open communication, attending all meetings, producing deliverables to a high quality and on time, and following all laws and company policies.
