Looking back, 2020 was filled with uncertainty and trepidation. Would we be able to open a Technical Communication class at Our Best Words on Zoom? Would Covid-19 allow our students to work and study? How many would lose their jobs? How many would get sick? So many questions, and at the beginning there were very few answers.
As the year progressed, we discovered that not only did we have enough students to teach, but we also had four successful internships and amazing final projects. Our students were challenged intellectually and technically. They learned complex concepts, complicated tools, and how to create workflows and diagrams. In the end, we persevered and rose to the challenge. They all successfully completed their projects and their work speaks for itself.
As a part of my Advanced Software Documentation module, my students learned about open source software and learned how to document APIs. I admit that I was a bit skeptical about bringing something so complicated to my students. API documentation is not for everyone. An Application Program Interface is an interpreter between two devices or endpoints, similar to a waiter who interfaces between the kitchen and the customer. Almost every software company uses APIs or develops them, so understanding how an API works and how to document it would be an advantage for any junior technical writer who is learning the tools of the trade.
If you have never looked at code, it can be quite difficult to really understand and document APIs correctly. I decided to use the open source philosophy and to ask the community for help. I contacted the Write the Docs group and they gave me so many ideas that I wasn’t sure how to use all of them!
Alex Fiedler offered to share his API Documentation Exercise and was always available to answer questions. His exercise was more complicated than I wanted, so I simplified it by restricting the choices, but I didn’t simplify the code. This modified exercise was the final project for the API mini-course, which was part of the larger Advanced Software Documentation course at Our Best Words.
Once I had the content, I decided that the API mini-course was too short to allow me to teach a new API documentation tool such as Swagger or Postman. As the content was going to be hosted on GitHub, I wanted to give my students Markdown templates for writing the docs. The community answered this need as well. The Good Docs Project has templates for many kinds of docs including API documentation. Their templates include a readme which explains how to use each kind of template. It is written in Markdown and hosted on GitHub. Check it out and contribute to making the project better!
Whenever I had a question, the Slack group at Write the Docs was more than ready to help. Special mention to Alyssa Rock and Chris Ward, who were more than helpful in answering questions with patience and care.
So, if you have read this article to the end and are wondering how you can learn to write API documentation, here are some tips:
- If you want to learn the course with an instructor, Our Best Words offers a mini-course in API documentation as part of their Advanced Software Documentation course.
- If you want to teach yourself, there are some courses which are really good. Tom Johnson has a blog called I’d Rather be Writing.
- Learn a bit of JSON, REST, or Python. You don’t need to know how to write a program but you do need to know how to read and analyze one. In the same way that a psychologist learns statistics in order to be able to understand correlations, a technical writer needs to be able to read code snippets and understand what they do.
- Showcase your work. Use the static site generator from GitHub to create a website of your docs. If that is not an option, just host it on GitLab or GitHub.
Laura Novich MSc, Advanced TC Skills Lecturer
Laura Novich entered into technical writing in 1997 and has worked in both startups and fortune 500 companies in diverse fields such as virtualization, cybersecurity, and enterprise cloud solutions on both Windows and Linux platforms. Laura is a regular contributor to “Open Source” magazine, is a founding member of “Write the Docs Israel”, and is highly recognized for her contributions and maintenance to Fedora’s open-source documentation (in KVM). She is a frequent presenter at MEGAComm and has had speaking engagements at the Red Hat KVM forum and has attended several hackathons. Laura has won the prestigious Red Hat EXCeed award for her outstanding collaboration work as well as the 3Com 3Award for her outstanding work in managing the ATM documentation project. In her current role, Laura is building and managing an open-sourced documentation community at ScyllaDB, where developers, customers, and open-source activists can contribute.
Laura’s diverse career history includes educating new immigrants in English (ESL). In this capacity, she was selected to be a curriculum writer for her school district and a teacher trainer for the NY state ESL aptitude test (NYSESLAT).
Laura has a rich set of hobbies and volunteer work, which includes being a mentor for FIRST robotics teams, genealogy, baking, and cake decoration. In addition, Laura is currently documenting her grandfather’s extraordinary life and together with her husband, Jason they manage and maintain a community library with over 2,000 titles.
Laura has both a B.Sc. in psychology an M.Sc. in TESOL and is a licensed English teacher (K-12) in Israel and the USA. Laura is a Red Hat Certified System Administrator.