API Documentation: Useful Tools for a Technical Writer

During a recent meetup, I asked the attendees the same question, “What tools do you use?”

Centered around YAML/JSON

Two weeks ago, I had the pleasure to visit the Content Bytes event in Krakow, Poland. Barbara Czy? of Box discussed the creation of API documentation and associated challenges, while Pawe? Ch?odnicki of DocPlanner talked about the career of a technical writer in the AI era.

According to Barbara, the API documentation life cycle revolves around a YAML file that describes the structure of the application programming interface. If created in line with the OpenAPI specification, the YAML file enables tools like Swagger UI to automatically render the definitions and endpoints, displaying this information visually.

Understanding the structure of an API and its ongoing updates has a direct impact on creating and enhancing the documentation. Here, technical writers can not only aid engineers in covering new features with documentation missed, but also find inconsistencies, broken functionality, and other gaps.

When talking about challenges, Barbara mentioned how development changes may ruin the work done previously. To mitigate this, she suggested looking at oasdiff, a CLI utility helping to identify differences/changes between OpenAPI YAMLs/JSONs.

For managing API documentation, some other URLs/tools may be also useful, as per Barbara:

• Postman (a full-cycle platform that—among other functionality—enables you to inspect an API or play with it)
• Markdownlint (a tool to check markdown files and flag style issues)
• JSONLint (to format and validate a JSON file)
• Spectral (an engine for JSON/YAML that can be used to validate and enforce API style guide rules)

When asking other attendees about their tools of choice (right after the presentation), I also noted these:

• Oxygen XML Editor (for XML authoring/editing, which may be needed when working with documentation tools, such as MadCap Flare, or standards like DITA)
• MkDocs (a static documentation website generator with source files written in markdown, configured with a YAML file)
• Redoc (an open-source tool for producing web-based API documentation from an OpenAPI/Swagger description)

Besides, if you want to see how Swagger can be used to edit YAML and autogenerate docs changes in real time, have a look at this interactive playground.

Life beyond ChatGPT

Following that, Pawe? Ch?odnicki continued with his vision of a technical writer’s role in today’s world. While authors of any kind should inevitably master the art of prompt engineering, he also suggested an alternative path—to look more into design-related careers, documentation UX/UI analysis, etc.

Either option chosen, Pawe? expects that more T-shaped specialists will emerge, meaning that a person should be an expert in one field, but also possess a generalist mindset and a broader skill set. (Wikipedia reasonably notes that this aligns with the concept of a cross-functional Scrum/Agile team.)

When answering my questions about useful tools, Pawe? suggested looking at Hotjar for exploring documentation visits/analytics. The tool provides heatmaps and offers insights into what your users are really reading, clicking on, etc.

Talking about intersections with other professions, I wondered how we could help business analysts, product owners, and project managers when acting as technical writers. However, all the participants delivered the same answer: in their companies, it is usually the other way around. That means, the writers typically turn to subject matter experts for information (e.g., for release notes or API details). Therefore, I shared my recent experience with architecture diagramming and crafting project vision documents—as a different approach.

Still, what about AI adoption? In contrast to the writers’ meetup held in May, most attendees told me that they had started using tools like ChatGPT lately. For instance, to understand the code they describe. I also appreciated the input from one participant who disclosed he had been actively using Atlassian Intelligence for Confluence. (The functionality is only available on premium/enterprise plans though.) In Confluence, it is now possible to summarize pages with an AI assistant, generate page drafts, find action items, fix grammar/spelling, etc.

I’ll say it again: the world as we knew it no longer exists, it is changing very rapidly.

It’s worth mentioning that, a week after the meetup, I spoke with another technical writer about the event and the topics discussed. According to her, customers have begun requesting tech writers with AI skills recently, but, at the same time, they often do not understand what specific skills are needed. I mean, literally, they may request AI-something, without clarity on what that entails. So, this was a good example of how AI adoption looks in practice sometimes.

However, during a very insightful discussion with Micha? Skowron who also attended the event, I liked his opinion that it is not the knowledge of tools that matters most. Understanding HOW to write and skills/experience in creating expert-level instructions and how-tos may ultimately be more beneficial. After interviewing dozens of writers (and screening hundreds), I do agree that it is easier to learn a trendy tool than to cultivate the right writing mindset, style, and proper background.

Want more?

The next Content Bytes meetup will take place on October 30. The upcoming event will be organized in collaboration with girls.js.

Thanks to Forte Digital Poland and Apify for hosting and sponsoring/supporting the latest meetup. My respect and gratitude to Barbara Czy?, Pawe? Ch?odnicki, Micha? Skowron, Micha? Olender, Agnieszka Wierzbowska, and other professionals for awesome in-person discussions during the networking part—about Rest APIs, markdown, XML/JSON, Swagger, AI, and more. Besides, thanks to Olga Stefaniuk, Edyta Rakowska, Adam Turlej, Pawe? Kowaluk, and others for the positive energy.

In case we spoke at the event, but I failed to find you on LinkedIn, feel free to connect! If you want to see other recaps and photos from the event, here they are: #1, #2, #3.

Looking for a technical editor, a head of tech content, a project manager, or a product owner? Drop me a line, and let's fix what’s broken or address the urgent needs.

Further reading:

• Technical Writers' Meetup: Content Structures Matter
• A List of 30+ ETL Tools Using AI/ML
• BA in the Era of AI: Opportunities vs. Threats