EN 
DE
ES
FR
PT-BR
AI Summary
- Mark Wentowski is an API documentation Specialist at TechWriteX. He entered technical writing because it combined writing and technology, and later focused on API documentation after discovering Tom Johnson’s blog and API documentation course.
- API documentation includes developer experience activities such as interviews, remote usability tests, crowdsourcing surveys, questionnaires, and reviews, alongside requirements gathering, drafting, reviews, and publication.
- Swagger documentation is automatically generated from the Open API specification, which defines the overall structure of how an API is coded. Conceptual documentation includes user guides and getting-started content that guides developers toward using the API quickly.
- Challenges include operational silos between customer-facing and documentation teams, second-hand information, and learning Git, Markdown, and Static Site Generator tools. Quality documentation enables writers to focus on strategy, research, features, and reviewing stakeholder contributions rather than reducing workload.
- Mark recommends Astro docs, advises staying curious and asking questions, and describes documentation as a broad field beyond requirements gathering and writing.
AI-generated content. It may contain errors.
See Document360 in action
Mark Wentowski, API documentation Specialist, at TechWriteX, talks about the various components, challenges, and best practices in the API documentation space.
Watch the Video Podcast here
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:
