A few weeks back, I joined Upwork which is a platform for freelancers looking for remote work. The amount of work available is staggering. Although there are many individuals asking for a tech writer to “help make my docs pretty” or proofread their dissertations, there are plenty of actual organisations from all around the world wanting to hire people for meaty long and short-term gigs.
Interested to see how many were seeking tech writers with API docs experience, I plugged in my search criteria and had a look. There is definitely a need for this skillset.
One company, Nextory, stood out. They were asking for a writer to transform their REST API definition into OAS. They even had a dump of their Confluence page in MS Word and had attached it to the job posting. I downloaded it.
Over the past couple of weeks, I have been practicing on Nextory’s API definition. There are plenty of endpoints, and although much of it is in Swedish, I have a general understanding of what the API does. So far, I have defined two endpoints and written a whole bunch of conceptual docs. Of course, much of it is guesswork and there are gaps because I don’t have access to the developers to ask questions, but I’m doing OK.
I also got a little help from New York-based tutor Ian at Wyzant, an excellent online resource for remote tutoring. He helped me to understand more about the data structures and what a developer would need to have available in the response schemas and parameters that can be passed with each call to the API.
My plan is to document three or four endpoints in the OAS then contact Nextory to show them my work. Hopefully they’ll like what they see and allow me to finish it (with access to their devs!).
The tools and techniques I’m using are:
- Github for storing markdown and YAML files and so that Nextory can access them easily when I contact them.
- Stoplight Studio for docs. This includes the conceptual docs (getting started, error codes, code samples etc.) in markdown, and the actual API definition in a YAML file using the OAS format. Stoplight also shows you how the definition is rendered in a web preview as you build your YAML. It also has a handy UI so you don’t have to learn the YAML syntax 100%.
- Tables Generator for creating tables in markdown in a human-friendly format (they are tricky to do in raw markdown!).
jodywinter.com 