What are APIs anyway?
Introduction to APIs
When people use the term APIs, they are not all talking about the same thing. This used to confuse me early on, so I’m going to give you a very quick tour of APIs. If you want more in-depth knowledge, there is a ton of information online.
To start, API stands for Application Programming Interface. It’s a way that software can exchange information with other software. Since knowing how to document APIs is in very high demand for software technical writers, I’m going to also provide resources for learning more about each type.
There are two main categories of APIs. Library APIs and web APIs.
Library APIs
Library APIs are software components. You don’t want to have every possible software library already included in your program or else it will take up a lot of space and it could really slow down your program. Instead, you include the software components you want when you need them in your program. For instance, if you’re not including images in your program, you don’t need to import an image API. How do you learn about these APIs? When learning a programming language, you usually learn about some of the common library APIs for that language. If you were learning to program for Windows, you might start learning about the available Windows APIs.
Examples of library APIs
Web APIs
Web APIs are also software components that can communicate with existing software, but these can be accessed through the web. Web APIs have been increasingly popular in the last few years, because anyone with an internet connection can access them, often for a fee. Web APIs come in several different types. Here are the most popular ones.
REST APIs
Representational State Transfer. This is an architecture for the web. You can request, add, update, or delete resources. It is also the most common type of web APIs available, and one that shows up in a lot of technical writer job descriptions. If you want an excellent free course to learn how to document REST APIs, go through Tom Johnson’s API documentation course.
Advantages
It uses HTTP, which the internet is built on. It also utilizes the newest innovations of the internet, such as HTTP2. There are a lot of free tools for use with REST, and much of what is out there is open source, so companies can take the source code, modify it, and make it their own. When OpenAPI specs are used, these APIs can be easily navigated for the average user.
Examples of REST APIs
gRPC APIs
Google Remote Procedure Call. This is Google’s version of RPC, and it calls methods (a programming term for actions) on the other machine directly. You can call methods across the internet as if they were already on your machine. While there are fewer gRPC APIs in use, the number of transactions worldwide are the highest. For instance, YouTube uses gRPC. Imagine how many transactions per second happen on YouTube! These APIs are much more often closed to the outside, so others cannot use them. You can learn much more about gRPC here.
Advantages
It’s fast. Really fast. In general, it’s about 7 times faster than REST APIs. It’s also great for programmers, because they can use a programming language they already know, and it’s like calling a method on another computer as if it was the same computer.
Examples of gRPC APIs
GraphQL
Data query and manipulation language, which includes the runtime to make these queries. Whereas REST was an architecture, and gRPC was a way to call methods, GraphQL is a query language. With it, you can request data, add to the data, change the data, or delete it. It was created by Facebook to solve some of the problems with REST APIs, such as overfetching or underfetching, or having easy ways to deal with different versions of the API. I won’t explain all of that here, but you can learn a lot more about it on the GraphQL Foundation page. That site also has a good tutorial for all the basics.
Advantages
GraphQL solves several issues that come up often with REST APIs. With REST, you request resources, and often several things are given in one request. For example, if you request book information, you may get the title, author, ISBN, and date of publication. But what if you only want the title. Then you are overfetching. You don’t need all the other information given. Let’s say you are doing this thousands of times for different books. It might be costly and take up most of your internet bandwidth, because you are getting a lot more information than you need. But GraphQL only gives you exactly what you ask for. Therefore, it is much more efficient. There are other advantages too. See the GraphQL Foundation page for more.
Examples of GraphQL APIs
Final thoughts
I learned recently that some companies are now using gRPC or GraphQL for the underlying API, but then use REST as the customer facing API. Evidently this offers some advantages, and is becoming more common now.
There are other kinds of APIs out there too, but these are the most common currently in circulation. I know I didn’t go into much detail here, but it’s a start, and you can use the resources I’ve provided to learn more.
Getting experience – Part 3
Get experience with an open source project
GitHub | Linux | GNU | Sourceforge
Common advice
The idea that you can get a job in technical writing by volunteering to write documentation for an open source project has been around awhile. This advice often appears in blog posts, tech writing forums, and advice columns. The prevailing logic is that you can add to your portfolio by writing documentation for some of the many open source software projects available. This shows off your tech skills as well as your writing ability, and is a kind of real-world experience. It sounds good on paper, but has some real problems. Let’s begin with a story.
Story 1
There once was a woman who dove into an open source project, writing some of their technical documentation, which eventually led to her getting a job at Facebook. True story. It really happened. You can read more about it, or even watch the video here: From Open Source Volunteer to Full-Time Tech Writer.
This is a really inspiring story, but before you start looking for an open source project to contribute to, consider the following:
- She had been an aerospace engineer for 15 years.
- She said nothing made sense (in the open source project) for quite a while.
- She first got noticed through her own blog, rather than anything she published on the open source site itself.
- She was trusted with maintenance of the main website for the project after a while, so they gave her an unusual amount of access.
- The open source project she worked on had an astronomy module, and her undergraduate degree was in astronomy.
- She mentored students for the Google Summer of Code because of her degree and background. Her mentoring also helped her make the connections she needed to get the job at Facebook.
Now let me tell you another story.
Story 2
Once upon a time I started learning API documentation, thanks to Tom Johnson’s excellent course. I finished his course, and tried to contribute to an open source project, as he recommended. I couldn’t do it. I figured I just didn’t know the material well enough, so I went through Tom’s whole course again. Again I tried to find an open source project to contribute to, but again ran into a brick wall. Knowing I was still no expert in API documentation, I went through the whole course a third time. It always takes me three times to learn something well anyway. After the third time, I felt like I really knew this stuff. I jumped on GitHub and tried to find somewhere I could contribute to API documentation. I went through hundreds of projects, but couldn’t find anything I could contribute to meaningfully.
Granted, I’m no expert, and maybe if I had spent months really digging into things, I could have made some progress. With enough time, most things are possible. Still, here are some of the issues I ran into:
- I didn’t initially realize the differences between library APIs and REST APIs. I should have figured this out, since Tom does mention both in his course.
- Many of the projects just weren’t active anymore.
- Developers did not have time for me. Remember, most of them do this in their spare time, after their day job.
- Related to the point above, often their requirements for a technical writer is that they should read the code and figure out what’s going on with little to no help. Then they should contribute. Later, I learned that even seasoned developers usually take 3-6 months before they can understand a complex code base well enough to contribute. This means, it would likely take me around 6 months, even if I was a seasoned engineer.
- Many projects were so complex, I could not even figure out what they did, let alone actually contribute to any API docs for it.
- I also couldn’t figure out how to install the software, or all the dependencies I needed to get started.
- Project contributors often assumed I understood a lot of inside knowledge of their technology or related technologies, such as dependencies.
Keep in mind, a developer would need to give you certain things before you could even get started.
The minimum you need to document an API
- The API base path.
- Endpoints.
- All possible methods and parameters, with descriptions.
- An API Key (If required), or how a user can get an API key.
- Status and error codes with what they mean.
- Open lines of communication with a developer who can quickly answer any questions about the project.
How about if you decide you want to document code samples rather than APIs. Documenting code is a big part of being a technical writer as well. In that case, here’s what you would need from the open source contributors.
The minimum you need to document code
- Code samples.
- Detailed notes or a description of what each sample does and how to use it.
- Direction on what parts of the code can be altered to fit the developer’s needs.
- Open lines of communication with a developer who can quickly answer any questions about the project.
However, most engineers expect you to read the code and find these things out yourself.
Even if you are documenting code samples, and not APIs, the developer will need to give you a lot for you to get started. Because the truth is that most technical writers do not create their own code samples. They are given the samples by software engineers, along with some sort of explanation. Yes, tech writers ask more questions to fill in the missing pieces. They add the parts developers might assume others know, just because they know the code so intimately. Technical writers also improve the instructions, grammar, organization, and navigation. Sometimes they even find mistakes in the code. But most don’t pull the code out of their own heads, nor do they intuitively know what the code does or how it’s used.
Often, the most difficult thing to get is the last item in each of the two lists above. In fact, it is nearly impossible, for all practical purposes.
What to look for in an open source project
- The project interests you. You might spend a lot of time here.
- You can figure out what the software or API does.
- The project is active, with an active community.
- They clearly have a need. They either say so in their contributions page, or there is a ticket that says so, or you see a need and offer to work on docs and they say that would be great.
- One of the contributors is willing to walk you through the code, or API, telling you what each piece does. This may be a huge barrier. They may think that if they were to spend that much time helping you, they might as well just write the documentation themselves.
- They already have good comments in the code that you think you can use to get started.
- Someone who is part of the project is very responsive and patient to answer your questions quickly.
- You believe you can write documentation from scratch for the project, not just touch up existing pages.
- You can actually get the software installed (if it requires installation) and get it working in order to try things out and document the software. This may require the installation of certain compilers or interpreters for programming languages, frameworks, other open source projects, and more.
If you already have experience with a technology, or a programming language, you can start there. For instance, if you’ve been learning about Blockchain lately, you may want to look up Blockchain projects. Or if you have learned some Java, you can look up Java software. There are many great guides for how to contribute to GitHub. But first let’s decide if you should even start down this road.
If those you reach out to say they expect you to read the code and figure it out, move on. Unless you can really do that. If you can, ignore my bleak advice. Maybe you can really do this.
To make headway in an open source project, it may take months to even start to get your bearings on a project. And then more time to contribute. Even such writing samples, an interviewer may still ask, “So, how many years of full-time technical writing experience do you have?” I have had that question asked of me more than once in a job interview. No writing samples can get over that obstacle.
What employers actually want to see in sample work
1. Step by step, numbered instructions that include:
2a. Code samples in some of the steps, clearly explained.
or
2b. API docs, with endpoints, parameters, etc. with steps for how to use the API.
3. It’s all your work.
You must include 1, 2a or 2b, and 3 in order to be taken seriously by an employer.
One issue with contributing to an open source project is an employer doesn’t know how much of it you did. Ideally, you want to create whole docs yourself. Adding a paragraph to a page will not get you a job. Fixing a readme page will not get you a job. See #3 above.
Will working on open source get you a job? Two more perspectives
I recently encountered this Reddit post:
Does volunteering like this actually lead to a job? Can anyone confirm they got a job by starting here?
After a number of people failed to answer the question, one person replied with,
The silence is pretty deafening.
That’s about what I expected.
I think this is one of the most often quoted pieces of advice out there that seems to have very little data to back it up. I have only heard of one person getting a technical writing job through contributing to open source. Therefore, this should probably be considered a fringe case rather than a normal pathway.
I prefer actual data, rather than”broscience” when giving out advice.
Another blogger says about this method:
I reiterate, this method (contributing to open source) is not advised for those seeking entry into technical writing or relatively fresh in the field. I say this because there’s usually very little hand-holding and you are expected to hit the ground running.
My conclusion
I am not going to say it is impossible to get a job by contributing to open source. I can only say that it seems hard. Really hard. I might also add it seems unlikely. However, if you are an ex-developer, or have specialized knowledge, maybe you can ignore this post and make it work. And if you have months or years to burn, you could probably find a way eventually.
For others trying to make the transition into technical writing, I would recommend that you go back and see my first two blogs for ways to get experience that might lead to a job.
If you know other people who have contributed docs to open source projects, which led to them getting a job in technical writing, I’d love to hear about it in the comments.
