Should Technical Writers Learn HTML?
Technical writers who use authoring tools like MadCap Flare may find it helpful to have a basic understanding of HTML. In the event that the text editor malfunctions unexpectedly, you will be able to fix the content manually by tweaking the HTML code. It gives you more control over your project—think of a manual transmission car as opposed to an automatic transmission car.
Personally, I've had to resort to the HTML editor several times to fix the content—there might be space or layout issues that the regular editor would simply refuse to correct.
On this page, I am going to provide the following information:
- Basic HTML information
- Most commonly used HTML tags
- Try-it-yourself examples
- How to edit HTML in your technical authoring tool
This page does not intend to be:
- A comprehensive overview of all existing HTML tags
What Is HTML?
Simply put, HTML (HyperText Markup Language) is a markup language that can be used to structure websites.
In the world of technical writing, HTML can help writers determine the basic structure and layout of their online help systems.
HTML Tags Explained
The HTML tags help the browser determine how the content should be presented. Each tag has its own function. For example, the text in the heading tag appears more prominent in comparison to other text on the page, the title is shown in the title bar, etc. The function each tag performs can be (usually) figured out from the name.
Consider the above HTML example. It forms the basic HTML boilerplate code i.e, the basic elements required for your webpage to spring into action.
Technical writers need not worry too much about learning the boilerplate code by rote as most technical authoring tools automatically generate the code (with additional parameters) as soon as you create a topic. Your main goal should be to understand what each tag does.
The example code shown above will create a simple web page with a title and a heading.
The table below explains each of the tags used in the example. These are some of the most common HTML tags you will find in authoring tools.
The start of an HTML page.
The end of an HTML page.
The start of the HTML page head. This part includes the title of the page and may also contain metadata (a prime factor in SEO), scripts, links, style, etc.
The end of the HTML page head.
The title of the page. It is shown on the title bar of the browser window.
The end of the page's title.
The start of the page body. This part is where you will enter all the webpage information like text, images, tables, etc.
The end of the page body.
The heading h1 will be displayed as a level one heading on the page, i.e., it will appear more prominent than other headings.
The end of heading h1.
The start of a paragraph inside the body of the HTML page.
The end of the paragraph.
As shown, the HTML tags come in pairs, each with an opening and closing tag (denoted by a "/"). When you open a tag, it is necessary to close it. For example, if I do not close the <h1> tag with a </h1>, the page's entire content will be considered a heading.
Try It Yourself
Let's build a simple HTML page using Notepad. Many developers frown upon the usage of Notepad. However, since we are not planning to become full-time web developers, we can start with the most basic application for ease of learning.
- Open Notepad.
- Copy-paste (or enter) the HTML Example mentioned previously. (I would recommend typing it out from memory. It is a great way to cement what you have learned.)
- Save it as test.htm.
- Double click to open it in a browser.
- Congratulations! You have created your first HTML webpage all on your own.
Observe where the text "Hello World" and "This is a Heading" appears on-screen.
Now start experimenting. Remove </h1> and see what happens in the output.
We will be tweaking the HTML example as we go along, so don't delete it yet!
The <h1> tag depicts the largest heading on the page. Its font size is more significant than other headings. The heading becomes smaller as you increment the number. Change the h1 tag to h2 in your saved file to see this in action.
There are only six heading levels. They can be summed up in the following decreasing order:
h1 > h2 > h3 > h4 > h5 > h6
Previously, I had mentioned that each tag has an opening and closing tag. Some exceptions exist, such as the line break tag <br /> that functions as a self-closing tag.
Some self-closing tags are listed below:
|Self-Closing HTML Tag||Explanation|
The content entered after this tag will appear in a new line.
Insert a horizontal line that takes up the entire width of the page. It can be used in any way you please but a typical usage is under or above a heading to enhance the design.
Try It Yourself
HTML Element Attributes
By default, the browser renders a particular style for each element. What if you want to modify the element's default style? It can be done using attributes.
Let us consider the <p> tag. We want the content in this paragraph tag to appear in blue with a font size of 10px and make it appear centered. For this, we can use the attribute "style".
<p style="color:blue; font-size:10px; text-align:center;">
You can view more attributes by googling for "<element name> attribute".
Try It Yourself
This example will generate a paragraph in blue with font-size 30px aligned to the center. A horizontal line is also displayed after the heading.
Tweak the values of the paragraph properties and check how the changes affect the output.
It is good practice to insert comments in your code to make it easier to understand later on. The comments will not be published in the final output; they are for your reference only.
The comments are inserted in the following manner (an angular bracket, followed by an exclamation mark and two dashes; it is closed by two dashes and an angular bracket) :
<!-- This is a comment -->
Try It Yourself
Do you see the comments appearing in the output?
P.S: If you do, double-check the syntax.
The Next Major Step
The next step for technical writers is to test the HTML example in their work-designated authoring tool.
The steps would be more or less the same in all tools:
- Create a new HTML project.
- Add an HTML topic/page.
- Make sure to shift to the HTML editor for the page.
- Enter the HTML example. Most of the generic tags will be autogenerated in the topic. You might only need to enter the page content in the <body> tag.
- Add the page to a Table of Contents (TOC).
- Generate the output and check how it appears.
For More Information
Google is your best friend!
HTML is vast and beyond the scope of a single page. This article only contains an overview of the most basic HTML tags used in structured authoring tools. In order to gain a deeper understanding of each tag, search for each tag on Google and explore how you can modify it.
Two valuable resources are MDN Web Docs and W3Schools. Check if they appear anywhere on your Google search results. In most cases, they will appear right at the top. Both the websites provide easy-to-understand notes and explanations, various examples, and do-it-yourself materials. Take maximum advantage of this plethora of information.
HTML is one of the easiest languages to learn. The more you practice, the more confident you will become at tweaking the HTML code in your help projects.
Reading any kind of code can only prove beneficial to a technical writer. It can help you understand the products better. It can help you understand developers better when they discuss the logic behind a newly implemented feature. So why not start with the most basic web development language? Give it a go. And don't forget to keep practicing!
Take a Moment to Vote
This content is accurate and true to the best of the author’s knowledge and is not meant to substitute for formal and individualized advice from a qualified professional.
© 2022 Dhanya V