14 KiB
Level up your HTML document with CSS
Use CSS to bring style to your HTML project documentation.
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.
Defining an HTML document
Let's start with a plain HTML document and explore how to add styles to it. An empty HTML document contains the definition at the top, followed by an <html> block to define the document itself. Within the <html> element, you also need to include a document header that contains metadata about the document, such as its title. The contents of the document body go inside a 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>
In another article about Writing project documentation in HTML, I updated a Readme file from an open source board game from plain text to an HTML document, using a few basic HTML tags like
and
for heading and subheadings,
for paragraphs, and and for bold and italic text. Let's pick up where we left off with that article:
<!DOCTYPE html>
<html>
<head>
<title>Simple Senet</title>
</head>
<body>
<h1>Simple Senet</h1>
<h2>How to Play</h2>
<p>The game will automatically "throw" the throwing sticks
for you, and display the results in the lower-right corner
of the screen.</p>
<p>If the "throw" is zero, then you lose your turn.</p>
<p>When it's your turn, the game will automatically select
your first piece on the board. You may or may not be
able to make a move with this piece, so select your piece
to move, and hit <i>Space</i> (or <i>Enter</i>) to move
it. You can select using several different methods:</p>
<ul>
<li><i>Up</i>/<i>down</i>/<i>left</i>/<i>right</i> to
navigate to a specific square.</li>
<li>Plus (<b>+</b>) or minus (<b>-</b>) to navigate "left"
and "right" on the board. Note that this will automatically
follow the "backwards S" shape of the board.</li>
<li><em>Tab</em> to select your next piece on the
board.</li>
</ul>
<p>To quit the game at any time, press <b>Q</b> (uppercase
Q) or hit <i>Esc</i>, and the game will prompt if you want
to forfeit the game.</p>
<p>You win if you move all of your pieces off the board
before your opponent. It takes a combination of luck and
strategy!</p>
</body>
</html>
This HTML document demonstrates a few common block and inline elements used by technical writers who write with HTML. Block elements define a rectangle around text. Paragraphs and headings are examples of block elements, because they extend from the left to the right edges of the document. For example,
encloses an invisible rectangle around a paragraph. In contrast, inline elements follow the text where they are used. If you use on some text within a paragraph, only the text surrounded by and becomes bold.
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> element, with other metadata. You can reference a file for the style sheet, but for this example, use a