Search results

Challenges in documenting long JSON objects

by Tom Johnson on Jan 21, 2016
categories: api-doc

Documenting long JSON objects (with hundreds of lines of code and multiple levels of nesting) can be challenging. There are different approaches to take, but none of the approaches seems to work well. I updated my API doc course topic with a section comparing the various approaches.

I’m now documenting an endpoint in a project at work that includes about 200 lines of code in a JSON object passed in the request body parameter. Inside the body parameter are various levels of key-value pairs and additionally nested objects (and sometimes arrays).

I added a section called Documenting lengthy JSON objects in request bodies in part of my API Documentation course to address the variety of ways people attempt to document long JSON objects. I think most approaches typically fail for this kind of documentation. What do you think is the best approach for documenting long JSON objects?

About Tom Johnson

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.