I recently wrote that you don't need to attain a high-level of coding skill for learning to code to be useful. A technical writer can see substantial ROI from just learning enough to be dangerous.
Which raises (not begs!) the question: How much is enough? What topics should tech writers know? And how well should we know them?
To start answering that question, I'd like to expand what we mean by "learn to code" or "knowing how to code" to "developer skills" in general. Too much focus on coding overlooks the other highly useful things that developers know and do that tech writers can benefit from.
Further, we need to distinguish between two (overlapping) sets of developer skills:
- skills that you might directly use as a tech writer
- skills that help you understand the technology you write about
For example, I use Python a lot as a writer. I can hack together little scripts to help me automate things. This blog is built on Nikola, and I use Sphinx a lot for building documentation --- both built in Python, and I have just enough Python skill to debug problems and add very minor functionality when needed. But I've never written documentation about something written in Python.
On the other hand, I have never once written a line of Java. I hardly know anything about the language, its ecosystem, or common tooling. But I've stared at enough of it that in context I can usually dumb out the sorts of things a tech writer might need to know about a web API written in Java. And I've had to do that many times.
Endless discussion board threads and subreddit questions about "what language should I learn" usually ignore this distinction. But it's a good idea to separate dev skills which are actually a subset of tech writer skills, and dev skills which are actually domain-knowledge about your subject matter.
Tech Writing Dev Skills
These are the skills that you can actively use in the course of being a tech writer, regardless of what you are writing about.
Comfortable at the Terminal
- Basic facility with navigation and file manipulation commands (
- General understanding of how commands work --- enough to quickly learn and use other tools you may need (
- Know how to open, edit, and close a file with
vi(you don't have to really know Vim or use it for authoring; just know enough to be able to edit files on unfamiliar machines ---
- Basic facility with Bash scripting --- just enough that if you find yourself typing the same sequence of commands over and over, you know how turn that into a simple script
- Lack of fear or anxiety, and the confidence to use Google or Stack Overflow to solve problems
It's great to know more, of course. Tools like
grep can help you search code bases; understanding
awk and other tools can help you with data munging and cleaning up text.
But knowing these simple things --- and especially being confident in your ability to Google and figure stuff out --- will make everything else easier.
Note: All of the above was relevant to Unix-like systems with Bash terminals (GNU/Linux and Mac). If you work in Windows, you may also need to learn the Windows/DOS-prompt version of all this. Or switch to a Unix-like system and be happier. I honestly don't know how to do any of my primary work without a Bash terminal. YMMV.
Basic Web Dev
- I have found understanding how the web is/was "supposed" to work (that is, as a web of documents, identified by URIs, and transferred via HTTP) helps me conceptualize content organization better. It also helps me understand why so many things about web development are non-trivial.
- Knowing (and caring) about "textual" HTML (all the inline elements) and their semantic meaning is helpful.
- Knowing what makes for good (valid, clean) HTML, and understanding proper separation of concerns helps me evaluate the quality of my tooling and prevents future redesign and reorganization headaches.
- Those last three items --- and a general focus on web standards --- give you a big head start in understanding web accessibility needs which too few tech writers care about, but we all should.
- Basic facility with CSS (LESS, SASS) gives me the ability to solve my own design problems. (For example, styling help text to mimic the UI being written about.)
Plaintext and Code Editors
- Being comfortable away from WYSIWYG editors and word processors is a requirement for most of the other tools I use.
- Fluency in Markdown has become nearly mandatory, since developers really like it and Github supports it by default.
- reStructured Text is a better tool than Markdown for documentation. It really helps to know reST and Sphinx, which is a static site generator designed for documentation. Like many static site generators, Sphinx is mostly run from the command line (another reason for you to get comfortable at a terminal).
If you're going to be writing Markdown, reST, or another plain text format, you'll need to find an editor you like. I use Atom myself, but Sublime Text, Notepad++, and [Vim](https://en.wikipedia.org/wiki/Vim_(text_editor) are also popular among writers. (And there are many others.)
One of the great things about plaintext formats is that, instead of everyone being forced to use the same software (Word or Framemaker, for example), everyone can use their own preferred editor. Developers have been able to do this for a long time, and now writers can enjoy the freedom to customize their workspace as they see fit.
git and Github
Git is a distributed version control system. Even though no one really understands it, it's become standard for many developers and development teams. If you're going to treat docs like code (which you should), some basic git skills are really helpful.
- basic git commands:
- general understanding of the distributed model, remotes, and common work flow with Github (fork, clone down, edit, commit, push, pull request)
- how to use Github pages and Jekyll (Developers tend to like these, so more and more startups are using them for docs --- if you're the first writer to show up, you be dealing with existing Jekyll docs written by the developers.)
Git is complicated, and can cause particular problems for writers. Perhaps the most important skill in git is the ability to keep calm, Google your problem, and know when to ask for help before you make things worse.
This is my favorite developer skill because it is actually coding, and makes me feel (I think?) like a real developer.
(I recommend Automating the Boring Stuff as a good intro to Python and what you can accomplish with it.)
Other Helpful Languages
Python is not the only good utility language for this sort of work. Bash is also very helpful, as I mentioned earlier. It's also not hard to learn, so the ROI is pretty high.
Ruby is the language behind Jekyll, the most popular static site generator, and also Ruby on Rails, the most popular rapid web application development framework. Ruby definitely has facility as a local utility language, but I don't know anyone who uses it that way who isn't also a Ruby developer generally. I'm trying to focus on dev skills for non-devs.
What about Perl?
Perl used to hold the place Python has assumed, as the "standard" utility and scripting language. I'm not sure there's a lot of need for tech writers to know it (I don't), but I'd feel remiss not mentioning it.
Every tech writer needs to know different things in order to understand the technology they are writing about. So, the following is highly conditional and probably not that helpful for tech writers already deep into a particular field.
This is intended as a general overview for people trying to get into the field or make a change.
I'm really of the opinion that for most tech writers --- even those writing developer docs --- the amount of target-language skill required is low, and can be acquired for most languages in a week or so.
Once you've acquired basic programming skill in one language, most other languages are relatively similar. You need a quick primer on the syntax, how typical things are done (loops, conditionals, function definitions, etc.), and anything unusual or weird about the language. Anything else you need to know you can probably Google or ask someone when you encounter. ("What's this
That being said, there are a handful of languages that are especially helpful. If you're interested in expanding your knowledge of languages (and you've already got a good handle on Python) you might look into these.
- Another reason to learn Java in particular is that it is the native language for Android apps. There's a lot of work available documenting mobile SDKs for cloud-based utilities. Knowing (at least a bit of) Java is a requirement for that.
- If you're interested in mobile SDK work, also get familiar with Objective C and Swift, which are both used for iOS development. Someone with decent facility in those three languages could carve out a nice niche working on mobile developer docs.
I could go on and on --- this language is popular in this industry, that language gets a lot of use for this other kind of work. That probably wouldn't be helpful.
If you're writing developer docs for a library, SDK, or language API, the most important language to know (if you need to know one at all) is whatever language they are using to build the thing you are currently documenting. Trying to learn languages in the abstract, in case you might need them as a tech writer, is probably not the best use of your time.
If you just want to have a better sense of programming in general, work on Python because you'll find it useful as a tool in its own right. If you have your heart set on a particular area or specialization (mobile, web, machine learning, etc.) find out what languages and technologies are popular there.
Systems and Architecture
Perhaps more important than understanding in particular language is understanding how software and systems work. As always, my view is particular, but --- it seems to me that a large percentage of people hiring tech writers need them to understand how the modern web works, how web and mobile applications communicate with servers, and how multiple system components connect to each other and to third party systems. I've had dozens of interviews over the last year and nearly all of them required a basic understanding of Service Oriented Architecture (whether or not they called it that) and RESTful web APIs.
Tech Writer Competency vs. Developer Competency
A big difference between developer skills for developers and the same skills for tech writers is the level of competence needed before being able to honestly say you are competent (read: put it on your resume).
For a developer to list some language on their resume suggests that they really know it with some degree of fluency --- that they can do the work of a developer in that language. But what does it means to do the work of a technical writer in a particular language? You should be able to:
- read some code and, given the context, figure out what it does
- write short (< 10 lines) code examples
If you know programming basics (that is, you know at least one language decently well) achieving this level of competence in a new language is pretty easy.
Have No Fear
It could be easy to read all this and think that I am saying something like, "You need to learn ALL THIS STUFF before being a real tech writer." Please know that is not at all what I'm trying to say.
I'm trying to say, as I was trying to say in my original post on the matter:
You don't need to know everything a developer knows, so don't worry about that. But there is a small set of developer skills which are easily achievable and which will make a huge impact on your productivity and career prospects.
I have personally been amazed at the gains I have seen in my own productivity, job satisfaction, and employability by acquiring and exercising developer skills which I continue to see as exceptionally mediocre. Much of those gains have come by letting go of my fear --- fear that people will judge my bad code, fear that I'll break my computer if I mess up at the terminal, fear that I'll type the wrong git command and destroy everything, fear that if I put a programming language on my resume I'll be called out as a fraud.
So far none of those things have happened.
What could you achieve with just a little more skill and just a little less fear?