Skip to main content

Basic HTML for Technical Writers: Lists, Images, and Links

  • Author:
  • Updated date:

I am a technical communicator who loves words and technology—not necessarily in that order.

basic-html-for-technical-writers-lists-images-and-links

Moving Beyond the HTML Boilerplate

The HTML boilerplate in authoring tools contains the basic tags needed to run a webpage, such as the "html," "head," and "body" tags. But how do we insert ordered and unordered lists, images, and links? These are additional elements that technical writers frequently use in their HTML documents.

In authoring tools such as MadCap Flare, technical writers can easily add all required items in a few clicks. But what if you require extra manual control? That's when knowing HTML tags can come in handy.

The information on this page is primarily meant for the following audience:

  • New technical writers with no prior HTML knowledge

This page does not intend to be the following:

  • A comprehensive guide of all HTML tags and attributes

1. Lists

You can insert bullets in HTML pages in two forms:

  • Ordered: Structured lists with each item in a numbered format.
  • Unordered: Unstructured lists with each item in a bullet point.

The below table displays the tags used for each:

HTML ElementPurposeOpening TagClosing Tag

ol

To start an ordered list

<ol>

</ol>

ul

To start an unordered list

<ul>

</ul>

li

To list items in an ordered or unordered list

<li>

</li>

HTML Example

<html>
	<head>
	<title>Hello World</title>
</head>
<body>
	<h1>This is a Heading</h1>
	<ol>
		<li>This is the first item of an ordered list</li>
		<li>This is the second item of an ordered list</li>
		<li>This is the third item of an ordered list</li>
	</ol>
	<ul>
		<li>This is the first item of an unordered list</li>
		<li>This is the second item of an unordered list</li>
		<li>This is the third item of an unordered list</li>
	</ul>	
</body>
</html>

If you save this as an HTML file and open it up in your browser, you will see an ordered and unordered list.

Lists Example

Lists Example

You can also create nested lists if required, i.e., insert a new list inside an existing list.

<html>
	<head>
	<title>Hello World</title>
</head>
<body>
	<h1>This is a Heading</h1>
	<ol>
		<li>This is the first item of an ordered list
			<ul>
				<li>This is the first item of a nested unordered list.</li>
				<li>This is the second item of a nested unordered list.</li>
			</ul>
		</li>
		<li>This is the second item of an ordered list</li>
		<li>This is the third item of an ordered list</li>
	</ol>
	<ul>
		<li>This is the first item of an unordered list</li>
		<li>This is the second item of an unordered list</li>
		<li>This is the third item of an unordered list</li>	
	</ul>
</body>
</html>

The following output is displayed:

Scroll to Continue

Read More From Toughnickel

Nested Lists Example

Nested Lists Example

If required, you can also create an ordered list with roman numerals by writing the <ol> tag as follows:

<ol type="I">

The other values that can be included in a <ol> tag are listed below:

SyntaxExplanation

<ol type = "i">

Start the list with small roman numerals. Example: i, ii, iii, etc.

<ol type = "A">

Start the list with alphabetical letters. Example: A, B, C, etc.

<ol type = "a">

Start the list with small alphabetic letters. Example: a, b, c, etc.

<ol start = "5">

To start the list with a specific number, such as 5 in this case.

2. Images

The image tag <img>, like the break and horizontal rule tags, is a self-closing tag. In other words, you need not explicitly close the tag to make it work.

The syntax of an image tag is as follows:

<img src="{Insert the local path or web URL of the image}" alt="{Insert image description}" />

The image can be hosted online or should be located in the same directory as your project. For example, in the case of MadCap Flare projects, the images are included in a folder that is a part of the main content folder.

HTML Example

<html>
<head>
	<title>Hello World</title>
</head>
<body>
	<h1>This is a Heading</h1>
	<img src="https://upload.wikimedia.org/wikipedia/commons/2/28/L%27amaro_caso_della_baronessa_di_Carini_%281975%29_-_Ugo_Pagliai_and_Janet_%C3%85gren.jpg" alt="this is a random image" />
</body>
</html>

In the above example, I have included a random image hosted on Wikimedia Commons. The output looks like this:

Image Example

Image Example

Place the image tag in the HTML document where you want the image to appear. I have placed it under the main heading.

The next part of the image tag – alt – is used to describe the image. Entering an alternative text is helpful during those times when the image fails to load on the browser. It gives an idea to the user about the missing image. It also helps with SEO. Google looks into the alt text to figure out your image. It may then display this image to the user in search results.

The following image demonstrates how a webpage displays a missing image with alt text:

Missing Image with Alt Text

Missing Image with Alt Text

In user guides, we avoid this practice of hosting an image elsewhere. It is best practice for technical authors to store their images within the project. This step ensures your online help is accessible and not dependent on other websites to display its content.

When you store your images locally, it is crucial to get the path of the image correct. The image does not load if the path isn't right. Most authoring tools make this easy, as you can copy-paste an image directly into the working copy. But understanding the tag and how to edit an image in the text editor can help technical writers. It gives us more control over how we wish to present the image, such as in the case of modifying alt text.

Do It Yourself

Carry out the following to add a picture to your HTML topic:

  1. Create a "Content" folder in your system.
  2. Inside the "Content" folder, add an image "Picture.png."
  3. Create an HTML topic and add it to the same folder.
  4. Link an image in the HTML topic using the following <img> tag and view the output in the browser.

<img src ="Picture.png">

In this example, both the image and topic are on the same hierarchical level. It might not always be the case, as the image could be located elsewhere. Change the path accordingly.

For example, if the image is located in a folder called "Images" inside the "Content" folder, then you have to link the image to the HTML topic using the following <img> tag:

<img src="Images/Picture.png">

You can use hyperlinks to navigate from one point in the user guide to another. In authoring tools, again, this process is easy. You highlight the word and then add a link using the link icon. But we aim to understand the tags better to achieve more manual control.

Consider the following example where the <a> tag is used to insert the Google website link:

HTML Example

<html>
<head>
    <title>Hello World</title>
</head>
<body>
    <h1>This is a Heading</h1>
    <a href=https://www.google.com/>Google</a>
</body>
</html>

Google is the anchor word. As with most tags, the anchor tag has an opening and closing tag. The attribute href is where you need to insert the URL. In user guides, you can also use href to insert bookmarks and links to other pages within the project.

In the output, when you click on the word Google, you are taken to the Google website.

Output with Google Link

Output with Google Link

Conclusion

Learning is just a Google search away. To understand each tag further, it is highly recommended that technical writers refer to comprehensive online resources such as W3Schools or MDN Web Docs and test the tags in their authoring tool.

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

Related Articles