15 KiB
Writing project documentation in HTML
HyperText has more features than plain text to level up your documentation.
Image by: Internet Archive Book Images. Modified by Opensource.com. CC BY-SA 4.0
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: <html> 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 <html> block:
<!DOCTYPE html>
<html>
<body>
</body>
</html>
HTML documents also need a <head> 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