Write HTML documentation with style

HTML makes it easy to publish content on the web. CSS makes it easy to style your content to make it look the way you want.

May 24, 2023

When you write documentation, whether that's for an open source project or a technical writing project, you should have two goals: The document should be written well, and the document should be easy to read. The first is addressed by clear writing skills and technical editing. The second can be addressed with a few simple changes to an HTML document.

HyperText Markup Language, or HTML, is the backbone of the internet. Since the dawn of the "World Wide Web" in 1994, every web browser uses HTML to display documents and websites. And for almost as long, HTML has supported the stylesheet, a special addition to an HTML document that defines how the text should appear on the screen.

You can write project documentation in plain HTML, and that gets the job done. However, plain HTML styling may feel a little spartan. Instead, try adding a few simple styles to an HTML document to add a little pizzazz to documentation, and make your documents clearer and easier to read.

Start with an HTML document

Let's start with a plain HTML document and explore how to add styles to it. An empty HTML document begins with the <!DOCTYPE html> definition followed by an <html> block to define the document itself. Within the <html> block, you also need to include a document header as <head> that contains metadata about the document, such as its title. The contents of the document body go inside a <body> block within the parent <html> block.

You can define a blank page with this HTML code:

<!DOCTYPE html>
<html>
 <head>
   <title>This is a new document</title>
 </head>
 <body>
 </body>
</html>

To demonstrate how to apply styles, we need a document to work with. Here is a paragraph from a "how-to" manual I wrote a few years ago about programming:

<!DOCTYPE html>
<html>
 <head>
   <title>Using Variables</title>
 </head>
 <body>
   <p><strong>Try to make your variable names
   meaningful.</strong> Avoid single-letter variable
   names. While short names like <code>i</code>
   or <code>n</code> are valid names, better names
   are descriptive like <code>count</code> and
   <code>score</code>. Your program's source code may be
   difficult to understand when you come back to it later
   and try to figure out what the variable <code>j</code>
   was <em>supposed</em> to represent.</p>
 </body>
</html>

This generates informative text that gets the job done, but doesn't have much visual flair:

screenshot of an HTML page with default styles — image: Jim Hall (Creative Commons)

Let styles do the work for you

You can apply direct styling to this document to change the font, colors, and other text styles, but a more efficient way to modify the document's appearance is to apply a stylesheet to the document itself. You can do that in the <head> block, with other metadata. You can reference a file for the style sheet, but for this example, use a <style> embedded style sheet within the document. Here's the HTML document with an empty stylesheet:

<!DOCTYPE html>
<html>
 <head>
   <title>Using Variables</title>
   <style>
   </style>
 </head>
 <body>
   ...
 </body>
</html>

Since we're just starting to learn about stylesheets, let's demonstrate a basic style: background color. I like to start with the background color because it helps to demonstrate block and inline elements. Let's apply a somewhat obvious stylesheet that sets a pale blue background color for all <p> paragraphs, and a light green background for the <code> source code samples. This also sets a light yellow background for the bold text, and a pink background for the italics text.

We'll define these using styles in the <style> block of our HTML document. The stylesheet uses a different markup than an HTML document. The style syntax looks like element { style; style; style; ... } and uses curly braces to group together several text styles into a single definition. Note that each style also ends with a semicolon:

<!DOCTYPE html>
<html>
 <head>
   <title>Using Variables</title>
   <style>
     p { background-color: ghostwhite; }
     code { background-color: lightgreen; }
     strong { background-color: lightyellow; }
     em { background-color: pink; }
   </style>
 </head>
 <body>
   <p><strong>Try to make your variable names
   meaningful.</strong> Avoid single-letter variable
   names. While short names like <code>i</code>
   or <code>n</code> are valid names, better names
   are descriptive like <code>count</code> and
   <code>score</code>. Your program's source code may be
   difficult to understand when you come back to it later
   and try to figure out what the variable <code>j</code>
   was <em>supposed</em> to represent.</p>
 </body>
</html>

If you view this updated HTML document in a web browser, you can see how the <p> block element is filled in as a rectangle while the <code>, <strong> and <em> inline elements highlight only the respective text. This use of contrasting colors may not be pretty to look at, but at least you can see the block and inline elements more clearly:

screenshot of an HTML page with updated styles — image: Jim Hall (Creative Commons)

This is a simple introduction to using styles in technical writing. Having mastered the basics, you might be interested in Mozilla's HTML Guide. This includes some great beginner's tutorials so you can learn how to create your own web pages.

For more information on how CSS styling works, I recommend Mozilla's CSS Guide.

Jim Hall is an open source software advocate and technical writer. At work, Jim is CEO of Hallmentum, an IT executive consulting company that provides hands-on IT Leadership training, workshops, and coaching.