Our favorite HTML how-to articles

HTML is the most widely used markup language in technical writing. While other markup languages exist, including DITA and Markdown, no other markup language is as widespread as the Hyper Text Markup Language. HTML is the de facto language of the Web. First implemented in web browsers in 1994, the language continues to evolve. Yet the basics of HTML remain the same.

In the last year, we shared several articles about how to write documentation using HTML. Here are four of our favorites:

1. A gentle introduction to HTML

If you are just getting started in HTML, use this gentle introduction to learn about the basic element styles of HTML: block and inline. Every HTML tag or style is either block or inline; once you understand how these work, you can learn how to use other HTML tags.

2. Writing technical documents 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.

3. Write HTML documentation with style

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.

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.

4. Write dynamic web documentation with javascript

Projects can have very diverse user groups. Some users might be very adept at using the system and need very little documentation. For these power users, documentation might only need to be reminders and hints, and can include more technical information such as commands to run at the shell. But other users may be beginners. These users need more help in setting up the system and learning how to use it.

Writing documentation that suits both user groups can be daunting. The website's documentation needs to somehow balance "detailed technical information" with "providing more overview and guidance." This is a difficult balance to find. If your documentation can't meet both user groups, consider a third option: dynamic documentation.