Do I need to learn HTML as a technical writer?
Discover whether or not HTML is a differentiator for your resume and career.
Short answer
Yes. Learn it. I recommend Mimo — it’s essentially Duolingo for coding.
Long answer
HTML stands for HyperText Markup Language. It is the standard markup language used to style documents across the web. That being said, most authoring tools and content management systems (CMS) provide you with a friendly user interface (UI) filled with buttons that automatically help you mark up documents. We typically refer to these interfaces as WYSIWYGs (What You See Is What You Get). Here’s what Substack’s looks like:
Many aspiring and early-career technical writers wonder if it’s really necessary to learn HTML if most publishing solutions do the work for you. The problem is, WYSIWYG editors are not perfect — far from it, in fact.
When WYSIWYGs Fail to Style Correctly
Let’s say that you are drafting a document that requires nested lists:
Step one; do this.
Step two; complete all of the following:
One
Two
Three
Step three.
WYSIWYG editors mess this one up all the time, and in more ways than one. This is because the editor you use to publish your documentation is usually not the tool you drafted it in. Usually, you draft your article in a collaborative tool like Google Docs, Confluence or any other tool that allows for stakeholder comments, suggestions, and revision history.
Once your article has been approved, you’ll copy and paste it into the WYSIWYG editor of your publishing solution and then quickly notice the styling is all wrong — the fonts aren’t on-brand, the spacing is weird, your screenshots have disappeared, your links have broken, and your nested lists are all over the place.
These issues cannot be fixed from the WYSIWYG interface. They must be resolved by viewing the HTML version of your document and, line by line, removing the artifacts transposed from your original document when you pasted it in.
Here’s a peek of what that looks like:
This revision process sucks. A lot.
But it sucks a lot less if you actually know how to read, write, and edit HTML.
On a normal day, the extra work of playing around with the HTML to get your document to display correctly might not be too stressful; only time consuming. But what about during a release? If you work for an enterprise-level solution supporting a portfolio of development teams building out multi-version software, it is going to be an absolute nightmare to stage 30 articles at the same time, for the same release date, and fix all of that HTML. In fact, you’ll probably have to do what we did at my first job: work nights and weekends during a release, spending hours literally just fixing documentation formatting for lists, links, anchors, screenshots, tables, and so on.
Knowing HTML is going to save you a lot stress in those moments (and potentially give you a lot of time back).
When WYSIWYG Options Aren’t Enough
Sometimes your documentation is going to need more complex styling than a standard WYSWIG editor can provide. Let’s look at two examples.
1. Notices & Callouts (Notes, Tips, Warnings)
Inserting a colorful or stylized note that’s nicely labeling can be extremely helpful to your readers—especially when this information might go overlooked (and, consequently, cause setup errors and a deluge of inbound support tickets). This requires knowing HTML and CSS to insert the callout styling into your document’s HTML view.
Example Notices
<style>
.notice-tip {
background-color:green;
}
.notice-warning {
background-color:yellow;
}
</style>
<div class="notice-tip"> This is a green text box with some friendly advice. <a href="twcg.substack.com">Read more here.</a></div>
<div class="notice-warning"> This is a yellow text box with some <b>important considerations</b> to take into account.</div>
2. Code Syntax Highlighters
When using code snippets in your documentation, it can be helpful to the reader to use a code syntax highlighter that colorizes the sample based on the conventions of the language being used. This is not a standard feature in most publishing platforms, and so you’ll have to learn how to install support for it onto your site and then insert it into your code samples from the HTML view of your document.
Example Highlight
Other Benefits of Knowing HTML
Knowing HTML sets you up with a foundation of understanding the way markup languages work, which is extremely important when trying to read unfamiliar code samples written in JSON, YAML, CSS, JS, and other languages. You will work with these languages, and many more, in your career as a technical writer (especially if you want to hit 90k+ salary ranges). JSON and cURL, for example, are essential to documenting REST APIs.
Overall, HTML is not something you should skip learning if your goal is to become a senior technical writer. Knowing HTML not only makes your life easier as an editor, it also acts as a gateway language to understanding more complex markup and programming languages.