Mark Wentowski, API documentation Specialist, at TechWriteX, talks about the various components, challenges, and best practices in the API documentation space.
About Mark
- Mark’s LinkedIn
- During his college days, Mark didn’t have many options to choose from. He discovered technical writing and loved it because it combined the two worlds of writing and technology. Eventually, he secured his first job as a junior writer.
- Later, Mark discovered Tom Johnson’s blog, “I’d rather be writing”, which inspired him and made him feel like technical writing was a perfect fit for him. As he delved deeper into the field, he came across Tom’s API documentation course, leading him to switch his focus to API documentation.
Key Takeaways
- In normal phases of documentation, you have requirements gathering, user research, drafting, reviews, and publication. Whereas with API documentation, there’s ‘developer experience’ which is almost like user experience. And it involves all the different things that you normally would do with user research such as interviews, remote usability tests, crowdsourcing surveys, questionnaires, and reviews, too.
- “One most common types of API documentation is swagger documentation, which is documentation that’s automatically generated from what’s called the Open API specification. Open API is the overall structure of the API, that says how the API is coded.” Mark adds.
- While speaking about different aspects of API documentation, Mark says “One aspect of it is writing intensive, i.e., conceptual documentation, which is mostly user guides in a sense as far as structure. It starts out as a boarding/gets started document where the developer is taken through the quickest route possible to using the API.”
- “The most challenging aspect of technical writing, especially if you are in a very large organization, is the operational silos of customer-facing teams and documentation teams. You are getting second-hand information because they give it from their perspective.
In addition, API documentation experts should get familiarized with Git, Markdown, Static Site Generator, etc. Technical writers are trying to get as close to developers as possible, using their tools and processes from them. There’s a learning curve and it can be quite challenging.”, He continues. - Responding to a query about whether good quality documentation reduces your workload, Mark says, “It doesn’t really reduce your workload, but it just means you can focus on other things besides writing. Say, adding features to your website or researching technologies or spending more time on strategy, you might outsource your writing to other stakeholders and become the reviewer.”
- “Having good quality documentation is a good thing because it allows you to sort of put on different hats and switch roles.”, Mark says.
Rapid fire with Mark Wentowski
- Highly recommended resource
Astro docs, an all-in-one web framework for building documentation.
- One word that comes to your mind when you hear documentation.
Mark feels that there’s a whole world around it- Not just requirement gathering and writing.
- A piece of advice you would give your 20-year-old self
“Stay curious and ask more questions to establish a relationship with people who has knowledge on the topic that you are interested in and wish to pursue.”
Subscribe to Knowledgebase Ninjas:
–