In my API doc survey, one of the questions I asked was the following:

How did you learn what you needed to know (e.g., Lynda.com, Safaribooksonline)?

41 people responded. The results look like this:

Once again, all answers were freeform, so I grouped similar answers into like categories. For "self-taught," people wrote things like trial and error, play, self, experimenting with code, taught self, practice, self-taught, experience, finding patterns, failure, started coding on my own, developing as a hobby, and experimenting with code.

For "online resources," people identified a variety of online resources, such as Skillcrush, Stack Overflow, Coursera, Lynda.com, Academic Earth, Safari Books Online, Cave of Programming, Code Academy, PluralSight, Google, and unspecified online courses/classes. There wasn't a particular online resource that dominated. Most had about 2 occurrences.

Three people said "On-the-job training," and one person mentioned a local chapter called Girl Develop It. I thought there was a surprisingly large number of former developers in the survey. Many of them wrote things like "I dev'd before I tech wrote" and, my favorite:

Lapsed developer. (I've forgotten more than most people will ever know…).

Yep, that's a developer attitude all right.

Analysis and interpretations

This was a good survey question, with no misinterpretation. A few people mentioned reading or "read everything I could get my hands on," so it was difficult to interpret whether they were reading online sources, offline books, or something else. But overall, the responses were informative.

Backgrounds as former developers

There were a lot of former developers who have turned to technical writing in this survey. About 3 out of 10 API technical writers in my survey used to be developers.

In my podcast with Andrew Davis, he said there are a lot of technical writers who are former developers in the Silicon Valley area. There are various reasons why developers turn to writing. Some find a passion for helping others learn, since they struggled through so much poor documentation (as Joe Malin noted in this podcast. Others prefer the writing life over the tediousness and pressure of coding all day.

Although it seems former developers would dominate API documentation, Andrew said that people with Humanities backgrounds bring strong writing and organization skills that rival the skillsets of former developers.

There probably are some advantages to being an outsider to coding. Being an outsider can prompt you to press for more clarity, it can help you avoid making assumptions about the audience's knowledge and awareness, and it might lead you to include more informative detail overall. (At least that's my hope, since I'm one of these outsiders.)

Learning from developers

One of the biggest takeaways from these results is that 46% of API doc writers learn from developers. Although developers can be tough to interact with, they can also open up a goldmine of knowledge into difficult programming subjects. I sometimes try to push along on my own, learning by myself because either the developer's explanations don't make much sense, or because developers don't take adequate time to really explain or show me something.

For example, yesterday I asked a developer to explain a certain field. He explained it in the right technical terms, I guess, but it still made no sense to me. He seemed to run out of patience when I didn't get it, and after the second reformulation (still as muddy as attempt number 1), I said okay I'll process it and maybe follow up later.

Some developers are good at unpacking difficult concepts, but I think it can be like walking into an advanced math equation. If you don't have the math background to understand advanced calculus, no matter how correctly or clearly someone explains it to you (e.g., Oh, it's simple. You see, the tangent line's slope is set equal to the derivative of the histogram function at the alpha point on the curve, and then you take the log function of the remainder. See? Uh, no. Can you run that by me again, this time as if you're talking to a four-year-old?)

No amount of explanation in these 5 minutes is going to clear it up. It reminds me of a scene from John Scalzi's Old Man's War. In that science fiction classic, a character who is a physicist doesn't even try to explain skip drives (a technology that allow you to skip space dimensions) to another person because, he says, "You don't have the math."

Learning on your own

Because asking developers can often be futile, the ability to learn on your own, to not be dependent on someone explaining something to you, can be critical. This is also something that Andrew Davis emphasized. He said companies aren't looking for tech writers who will need everything explained to them. They need to find ways to learn on their own, on their time, through the many resources available to them.

For me, learning on my own is critical. Coming back to the math scenario, if you can learn on your own, you can start at your level and slowly ramp up. Once you get fractions down, and algebra, and pre-calculus, you might be ready to unpack what the mathematician is saying when he or she explains the advanced differential calculus equation. But if you rely on engineers to bring you up to that level (in 5 minutes or less), you may not have much success.

My favorite online resources

I personally have found tremendous benefit in the many online resources available, particularly Safari Books Online, Lynda.com, Cave of Programming, Udemy, and other sources. Of course I regularly search for specific questions and land on sites like StackOverflow, Wikipedia, or other online tutorials, but when I need to learn something from the ground up, I need a well-structured online course or book that walks me through the basics, building chapter by chapter or module by module.

College classes

In some STC circles I've been in, I regularly hear people say they want to take some college classes to learn programming. However, while I think college classes wouldn't hurt, they don't so much fall into the self-learning category that is so inherent in the programmer's mindset.

If you really want to learn something, use the many online resources available to focus your learning on what you need to know, and then experiment, play, try things out, code little programs, and explore on your own to further your understanding.

My fear of taking an online class is that the pace will either be too slow or too advanced. The professor might set me about with a project that is largely irrelevant to what I want or need to learn. I'll end up doing exercises about something unrelated to my projects at work, and after the semester ends, all the learning will fade (what you don't use, you forget) while I still struggle with other tech learning needs on current projects.

Conclusion

Overall, while this survey question seems rather innocent, it relates to the biggest challenge that API doc writers noted: learning code. Without a doubt, understanding the technology is one of the most challenging aspects of API documentation. How do you learn what you need to know? According to my survey:
- Ask developers
- Use online resources
- Explore on your own
- Read books
- Maybe take some classes