By Samuel Wright
Jobs in the developer documentation space, such as API reference material, quick start guides, and programming examples, are on the increase. Which is all very well for writers who have moved over from working as a programmer, but how do technical writers without a formal programming background land these more technical roles? And how much programming do you really need to know before you can brag about your API documentation skills?
The bad news is, yes, you need do need to be able to read code to write useful API documentation. The good news is you do not need to become a programming expert (although that does help) and it is probably easier to learn than you think.
Picking a Programming Language
If you do decide to learn a programming language, the obvious one to start with would be the one in which the project you want to document is written. But even learning a different programming language will teach you concepts that you can reuse in other languages. So which programming language do you start with? Everyone has a different opinion here, so fall back on the best advice I’ve heard on the matter: “Pick the programming language you have most support for” (Jessica Rose, Close to Clever). Whether that is a friend, a colleague, or a buddy from a local programming language meet-up, having someone who can explain away the obstacles you are hitting in person makes a huge difference to how fast you can pick up a language.
Once you have picked a buddy and a language, ask him or her which online resources or books are best, and start working your way through those. Decide whether you prefer interactive tutorials or read-along guides, but either way make sure you actually write the code examples and run them because just reading the text won’t get you very far. Likewise, figure out if you prefer paper books or ebooks, and use what works for you.
Here is a list of some common programming languages with descriptions quoted from Wikipedia and a couple of tutorials for each one. I’ve intentionally not mentioned C++ or Java, as I think you’re better off learning another programming language before learning those.
Python
“Python is a widely used general-purpose, high-level programming language.”
Ruby
“Ruby is a dynamic, reflective, object-oriented, general-purpose programming language.”
JavaScript
“JavaScript (JS) is a dynamic computer programming language.”
PHP
“PHP is a server-side scripting language designed for web development but also used as a general-purpose programming language.”
- http://php.net/manual/en/tutorial.php
- http://devzone.zend.com/6/php-101-php-for-the-absolute-beginner/
It is worth bearing in mind that reading code that someone else has written is almost always easier than writing your own code from scratch, although at some point in your career you are bound to come up against something that looks like it has been written to be intentionally incomprehensible.
Picking a Project
Once you have chosen a programming language and worked through some tutorials, you may think you know how this programming thing works. The way to find out whether you know how to program is to find something that you want to program, and program it.
The ideal project is something non-trivial but useful and of interest to you, and in practice that means you often end up “reinventing the wheel.” Maybe it is a three-page blog, or maybe it is a command line program that lists all of the index markers in your XML documentation and downloads definitions for them from an online glossary. Whatever it is, you’ll find the process of figuring out how to write it invaluable when it comes to knowing what type of information developers need.
A Note on Generated Documentation
Most programming languages have a (more or less formalized) method of documenting code using code comments that are extracted and converted to HTML or PDF. When you are writing or editing this type of documentation, you’ll edit the source code files directly, so find out what format the comments are written in (often but not always a variation of Markdown).
The important thing to be aware of here is that code comment-generated documentation does not mean that documentation writes itself; it means that the documentation compiler takes care of the easy mindless stuff and lets you make sure the text actually makes sense and is useful for the programmer reading the documentation.
JSDoc is one way to document JavaScript code. The following example shows a function definition for a function called Book (the last three lines), with documentation in JSDoc format code comments (the first six lines).
/**
* Represents a book.
* @constructor
* @param {string} title - The title of the book.
* @param {string} author - The author of the book
*/
function Book(title, author) {
// This function does not do anything yet.
}
We’ll look at what sort of information we need to add to this documentation in the next section.
Considerations when Documenting APIs
So you have learned the basics of your chosen programming language and have an API to document. What now? When writing API documentation, what you need to keep in mind is that the developer can often read exactly the same code that you are reading, so what your documentation needs to do is add value on top of what can be easily gleaned from the code.
The previous JSDoc description of the Book function omits the following potentially useful information (this is not a complete list):
- What is the maximum length of the title and books strings?
- Is a one character title or author valid?
- What happens if you call the function with an empty string in place of the title or author?
- What other restrictions on the parameters are there? What happens if you call the function with values outside these restrictions?
- Does the function return a value? What type is it?
- Does the encoding of the string matter?
None of these issues (for this admittedly absurdly simple example) are at all specific to JavaScript, but the answer to all of them should be in the source code you are documenting. All you need to do is read it, using your newly acquired programming literacy.
Writing Good Code Examples
Good developer documentation is full of code examples, but you can’t just copy and paste code from a random file and expect it to illustrate your point! Each example should illustrate one syntax element or API endpoint, or be part of a longer ongoing example that you gradually build up. Avoid using code features that you have not yet explained, “cunning tricks” to save space, or complex optimizations— in code examples, clarity is king.
And always, always test your code examples! There is nothing quite so frustrating as copy and pasting a code example into a file, running it, and finding out that the author has not double and tripled checked the code. It is best to set this up so it happens automatically, that way you don’t have to worry about forgetting about it. Exactly how you go about this depends a lot on your authoring and programming environment, but a little extra effort upfront will save you a lot of headache and manual testing later.
Learning More
One downside of learning to program is that you will find it is like pulling at the end of a very large ball of yarn. There is an incredible amount of detail to learn, and an almost infinite list of websites saying they can help you learn it! Here are a few of the better ones:
- Learnable: An online learning environment providing access to online books, courses and video lessons focused on web design and web development. (Subscription based).
- Udemy: Online courses on almost anything, including programming (Subscription based).
- Coursera: Over 400 free online courses provided by universities worldwide.
- Stack Overflow: Ask and answer questions about programming topics — for when you can’t find the answer anywhere else.
You can also subscribe to mailing lists and IRC chat rooms, use Twitter hashtags, look for local meet-ups, and follow blogs.
A note on learning resources: as helpful as the people who write Stack Overflow questions and answers, blog posts, and tutorials are, don’t assume they are experts in their field, and don’t take answers as an indication of best practices. Yes, they might answer your immediate problem, or show you how to get a step closer to a solution, but do take anything you find on the internet with a grain of salt.
Doubts?
If you are still in any doubt, next time you see an interesting writing job that requires programming experience, remember which language they wanted. Look it up and try to learn it, and you might be pleasantly surprised. If nothing else, you can use the experience as an example next time someone at an interview asks you for a recent challenge!
Samuel Wright (@plaindocs) is a freelance technical writer, specializing in the minefield that is API and developer documentation. After working in various parts of the world, Sam chooses to live in Berlin, where he initially moved to work with Nokia. At Plaindocs he detangles API documentation and implements documentation systems and processes.
