I recently surveyed technical writers to ask a variety of questions about API documentation. Rather than present a summary of the survey all at once, I am presenting the results of each question on a post-by-post basis, so that I can properly analyze and interpret the results of each question. So far about 38 people have participated in the survey. Not a ton, but enough to make some decent conclusions. If you still want to participate in the survey you can. (The survey is ongoing.)
One of my survey questions asked the following:
Here are the results:
By the way, I'm not a charting wizard. A couple of people pointed out that in my previous post, I shouldn't have used a pie chart because the responses didn't add up to 100%. As a result, I updated that to a row of columns (like this one).
Also, this time I had 38 responses (6 more than last time). This survey is kind of growing as I analyze it. At the end I'll go back and redo all my calculations, but I don't anticipate that the trends will vary too much (so much that my analysis would become invalid anyway). Interestingly, the more I analyze the survey, the more people participate.
Note that this survey question is somewhat broad. It doesn't ask which languages are used most in their jobs, whether the languages they know correspond with the APIs they document, whether the respondents learned the language as a result of actual need or just as a hobby, how well they know the language, or whether their knowledge is current (maybe they learned C++ in the 90s and have forgotten it long ago). This question is just a general probe into the basic language familiarity in a small group of surveyed tech writers.
Correlations between REST doc and programming knowledge
Because respondents added their initials, I also correlated the answers that each person put down for “What type of API do you write documentation for?” with “What programming languages do you know?”
I thought that maybe those who just document REST might not know many programming languages. But actually, there wasn't a correspondence at all. Pretty much everyone in the API doc space is technical enough to be familiar with at least or two programming languages.
What does it mean to “know” a language?
A lot of people qualified their understanding of a language. They wrote, “minimal knowledge” or “basic familiarity,” or “just reading about it”, or “familiar with the basic concepts and structure”, or “understood from a ‘documentation' perspective…so code understanding is very loosely understood” or “just by reading about it. No programming (yet)” or “I'm most comfortable in docs/understanding frameworks.”
Level of proficiency is an important point. A tech writer putting "Java" on his or her resume implies different expectations than a developer putting "Java" on his or her resume.
It's assumed that a technical writer who lists a programming language on a resume has an ability to read code in that language more or less, but not necessarily write code like a developer. One needs to be familiar with the different components, the terminology, how it all works and such. But anything more than simple programming in that language isn't expected.
Even so, I think that the more proficient you are with a language, the better. To write good documentation, you have to test and describe the code at some level. To test the code, you need to understand it more or less. This might mean setting up a project in an IDE and or some similar task.
No doubt you're calling an API in your documented tasks, so you have to add elements that aren't usually covered in beginner tutorials. Of course, the level of detail and difficulty of all this varies widely based on the language, the API, the context, etc.
Quite amazingly, the top 7 responses align with the most common languages tech writers know!
I think the survey is an extremely important one. It can take months or years to learn a programming language. You certainly don't want to waste your time learning the wrong one. Suppose you decide to start with Visual Basic and spend months learning it, only to find that what employers really want you to know is Java.
Why are some languages more in demand?
I said that the languages tech writers know reflect the trends of the web. Sitepoint has a better analysis of why these languages are more in demand:
Their reasoning is as follows:
Perhaps it's not surprising to find Java topping most charts because it can be used in so many places: application development, server-side web development, Android development and — importantly — education. Many schools, colleges and universities teach Java so resources and questions are littered throughout the web. More recently, Python has gained traction as an introductory language so it will enjoy similar benefits.
Next, we have C and C++ which been around for 45 years in various incarnations. If all C-based projects ceased today, a rich history of the language would remain on the web for many years to come.
C# is slightly unusual given ASP.NET lingers at number 30 in the all-languages chart. That said, it has been in use for more than a decade and is almost as ubiquitous as Java. Many businesses sole output is Microsoft-based software.
Keep in mind that this Sitepoint survey is probably intended for programmers, not technical writers. But since technical writers work along side engineers, the two lists have similar applicability.
From their analysis, it seems that C and C++ are somewhat legacy languages that enjoy popularity based on their dominance for so long. And Python is more often learned as an introductory language. Because of Java's ability to integrate on the web through J2EE servers (e.g., Tomcat), it has a definite advantage for web-based applications.
Where to start
Often with more core programming languages (C++ or Java), about the only thing I can do is write programs that produce console messages based on some logic. Whooptido!
Some programmers tell me that, if I want to learn a language, I might want to focus on Scala, R, and other languages that are emerging. Despite this, I've never seen any job description looking for technical writers who know Scala or R.
Depth or breadth?
One question is whether depth or breadth is better with programming languages. Is it better to develop an advanced knowledge of Java at the expense of knowing other languages? Or is it better to be a jack-of-all-trades-master-of-none type of person?
My guess is the latter. Tech writers often interact with numerous programming languages and platforms. You don't need to be hard-core in every language (in fact, it would be nearly impossible without being a full-time developer). But you need to be able to navigate the landscape, understand the terminology, and know how to pick up information quickly.
I'm a technical writer based in the San Francisco Bay area. In this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, visual communication, information architecture, writing techniques, plain language, tech comm careers, and more. Check out simplifying complexity and API documentation for some deep dives into these topics. If you're a technical writer and want to keep on top of the latest trends in the field, be sure to subscribe to email updates. You can also learn more about me or contact me.