Writing project documentation in HTML

Documentation is an important part of any technical project. Good documentation tells the end user how to run the program, how to use it, or how to compile it. For many projects, plain text documentation is the standard. After all, every system can display plain text files.

However, plain text is limiting. Plain text files lack formatting elements like italics text, bold text, and titles. To add these elements, we can leverage HTML. HyperText Markup Language (HTML) is the markup language used in all web browsers. And with a little extra effort, you can use HTML to write project documentation that can be read by everyone.

HTML uses a series of tags enclosed in angle brackets to control how different parts of a document should be displayed. These tags define elements in an HTML document, such as document headings, paragraphs, italics text, bold text, and other kinds of text. Almost every tag comes in a pair: an opening tag, like

to start a paragraph, and a closing tag to end the element, such as

to end a paragraph. When using these tags, remember this rule: if you open a tag, you need to close it. Not closing a tag properly can result in the web browser incorrectly.

Some tags define a block within the HTML document, while others are inline. For more information about block and inline elements, read my other article about a gentle introduction to HTML.

Start an empty document

Begin by creating a boilerplate empty HTML document. Every HTML document should provide a document type declaration. Use the single tag on the first line of the HTML file to define an HTML document. The HTML standard also requires that pages wrap the document text in two block elements: to define the HTML document, and to define the body text. While HTML doesn’t require indenting each new code block, but I add it anyway so you can see that is actually “inside” the block:

html>

  body>

  

  /body>
/html>

HTML documents also need a

block before the that provides extra information called metadata about the page. The only required metadata is the title of the document, defined by the