Programming skills and languages for technical writers

The title of this post presumes technical writers need to learn a programming language, but that’s not necessarily true. If your job involves end-user documentation for example, that you create on a simple editing tool (one big bank I interviewed with said they use MS Word)—then you don’t have to know any language to succeed. Knowing how to code is not necessary, however it does help.

Why learn a programming language?

If you’re looking for a job, it may help your application if you can boast some coding prowess. For some jobs it may even be a requirement that you know some languages. If you’re planning to get into API documentation (and with increasing API usage, you might want to), then it really helps to know some level of coding to understand the API and how developers might want to use it. Not to mention the one thing developers want to see in API documentation are code samples.

In my limited experience, open source documentation seems to favour a knowledge of lightweight markup languages at the minimum (like Markdown or ReStructuredText). As tools for documentation creation become more complex (RIP Microsoft Word), it seems almost inevitable that technical writers will need some coding ability.

How well do you need to code?

There’s an interesting argument against knowing a programming language really well if you’re a technical writer. Think about how you approach writing—you consider effective ways of presenting information, you need to simplify complex information, and the whole process is quite open-ended and subjective. You’re engaging the parts of your brain responsible for creativity. Another writer might have a different approach to yours.

On the other hand, what do you think you need to get good at programming? Learning how to code requires logical, objective and binary 1Joke time! There are 10 types of people in the world: those who understand binary, and those who don’t. Ha ha h… thinking – which uses different parts of your brain. Learning how to code well will require you to start thinking in a different way—and the presumption is that this usually comes at a cost to the quality of your writing.

If this is true, it’s good news for technical writers. You don’t need to have an advanced level of proficiency in a programming language, you can aim to know just enough that you’re able to read a code sample and explain what’s going on.

Further reading: Enough to be Dangerous: the Joy of Bad Python

Programming skills to have

From my limited experience dabbling in open source so far (right now in Season of Docs), here’s what I think technical writers should know. But first, do you know how the Internet works? What about the difference between the Web and the Internet? (If you have a few minutes, watch this video I made for an organization explaining some Internet basics.)

Front-end web development

The Web today is pretty much entirely built on HTML, CSS and JavaScript so knowing how browsers render these three languages into web pages will make your life easier. If you’re starting from scratch, I really recommend you begin with HTML—other languages seem to be easier to learn once you know this. The tutorials on this site are good to begin with, or here’s another beginner-friendly one.

Text Editors

If you’re going to be writing in HTML or other markup languages, you’ll need to get used to working in plain text editors. Mac’s default editor is TextEdit, Windows is Notepad, I use Sublime Text and I’ve heard of Atom (there’s lots out there!). There’s also Vim, which is a command line-based text editor which leads us to…

Command line basics

Listen don’t fight it. Dealing with this after you’ve only had to deal with beautiful graphical interfaces may be like flying economy when you’ve only flown business class your entire life2 If this is you, I don’t want to know. . Or eating McDonalds after you’ve only ever had Kobe beef. At some point you’ll have to come face-to-face with the dreaded screen and its blinking cursor waiting for you to screw up. You might as well get to know this devil interface. Some basics:

• Command line interface (CLI) is the, well, interface that lets you type commands that tell the computer to do certain things. The program behind this interface is called a shell or command-line interpreter. The app for typing in commands (Terminal in Mac and Command Prompt in Windows) gives you access to the core of the operating software you’re using.
• When you see things like sphinx install  or   git commit in tutorials, these are commands you have to type in Terminal or Command Prompt.
• When you first open up your command line app, your prompt will point to a specific folder on your drive:

*Bash is the default on Mac and Linux, and because Command Prompt on Windows is not as powerful, I’ve seen some suggestions online for Windows users to use Cygwin instead.

From here, you can navigate between folders, create directories, list files, edit plain-text files etc. Check out the References page for a list of commonly used commands.

Git commands

You could use GUIs 3 Graphical User Interface for working with the git software, but if you want to not use a crutch and get proficient, using the command line to develop basic git skills is the way to go. I’m saying this after I spent all day yesterday trying to troubleshoot git issues, Googling the crap out of everything and nearly tearing my hair out—but this shite system is supposed to be complex. Just breathe.

I’ll be updating the References page with common Git commands shortly once I know what the hell I’m doing. In the meantime, you can follow my 5-step plan.

Lightweight Markup Languages

So if you’re using Github (what’s the difference between git and Github?), you’re going to have to know Markdown. This is classified as a lightweight markup language, and it’s probably the easiest to learn.

The other language that fits into this category is called reStructuredText (RST)—the default language used by Sphinx (a documentation generator). I’ll be doing a beginner’s tutorial on RST and Sphinx shortly, but for now here’s a short summary of the differences between Markdown and reStructuredText:

• Purpose: Markdown has a modest goal in life, i.e., to be a format for writing for the web (it can easily be converted to HTML). ReStructuredText is more ambitious—it was designed specifically for writing technical documentation. So if you want to write a simple no-fuss web page, then Markdown will do. But if you’re after something more robust, maybe API documentation, then you will want RST. There’s more to unpack here—RST uses mechanisms (called directives and roles) that make it more powerful (and verbose), but more on this in another post.
• Standardization: Markdown has many ‘flavours’ (implementations), there’s a whole list here that I didn’t bother counting. The subtle differences between the flavours may result in incompatibility if you’re writing using one flavour but it gets rendered in another. There is no such concern with reStructuredText as it is more formalized and can easily be converted to different formats.
• Semantic meaning: RST allows you to have semantic meaning within the markup. What this means is it can separate what something is from what it looks like4Like how oatmeal looks like prison food but it’s really good for us. Ok maybe not like that.. You can focus more on the words you write and less on styling. This is why HTML uses CSS for presentation too. Quick digression: In HTML, if you wanted certain sentences to appear in bold and red whenever you want to say something important, you could type in

<p style="color:red;">
<b>
   THIS IS REALLY IMPORTANT!
</b>
</p>

but you’d be a better programmer if you specified a class instead:

<span class="scream">
   THIS IS REALLY IMPORTANT!
</span>

and then in a separate CSS file, you would specify the formatting for that class:

span.scream {
              color: red
              font-weight: bold
}

ReStructuredText does one better by having a standardized set of class names:

.. important:: THIS IS REALLY IMPORTANT!

This class—important—has its own output format already taken care of, so you just need to focus on what you’re writing. Markdown, as you’ve probably guessed by now, does not have semantic meaning. You’d have to embed HTML if you want to grab the reader’s attention.

Conclusion: ReStructuredText is better for full-fledged documentation, Markdown is better for creating simple web pages.

Further reading: Eric Holscher (co-founder of Read the Docs and Write the Docs) on why you shouldn’t use Markdown.

Programming Languages

And finally, if you’re looking to sink your teeth into some legit coding (not that the others weren’t), and you’re undecided, get started with Python. Of course there are others (Java, Ruby etc.), but if it’s all the same to you, I’ve just heard Python recommended by a few people now. I’ve started it myself and am quite fascinated by it. Mosh here has an excellent marathon of a tutorial (free) for complete beginners (his YouTube channel has lots of beginner tutorials for other languages as well if those are more up your alley). Remember the tech writing goal here:

• Read and understand what the code does
• Write a few code samples

If you can do this, go ahead and put it on your CV. You don’t have to be fluent if you’re not a developer!

Conclusion

You don’t have to know all of this! It just opens up doors if you do invest the time to pick up some basic developer skills (again, you don’t need to be an expert), not to mention the increased confidence as you start doing stuff on the command line and holy crap—it actually works!