I Wrote a User Guide for My JSON Tool

I put together a 12-chapter guide for my offline JSON tool, with screenshots of the actual interface and sample data you can copy and use. It covers JSON formatting, code folding, data comparisons, JSONPath queries, and schema validation, along with some details I noticed while writing the instructions.

I recently wrote a user guide for Qudo JSON Toolbox.

Until then, most of my time had gone into adding features and fixing problems. Documentation was mostly handled by the README. It listed the available features and explained how to run and package the application, but it wasn’t quite enough for someone opening it for the first time.

Where does the JSONPath page load its data from? Why do query results still show the old data after you edit the document? What’s the difference between code folding and the tree viewer?

Those things felt obvious while I was writing the code. Writing the guide made me realize they needed proper explanations.

One Sample Document From Start to Finish

I didn’t want to turn the README into another feature list.

I prepared a small JSON document containing a project name and two users, with fields such as id, name, score, active, and tags. The whole guide uses that same document.

You start by opening the file, formatting it, and minifying it. Then you deliberately remove a comma to see how the tool reports the error. After that, you collapse an array, expand a few tree nodes, and locate a field.

In the comparison chapter, you change one user’s score from 72 to 82. For JSONPath, you query users whose scores are at least 90. Schema validation uses the same data: change a score to 120 and check why it fails a rule that sets the maximum to 100.

Keeping the example simple means readers don’t have to understand a new set of data in every chapter. It also makes it easier to tell whether an operation produced the expected result.

The Screenshots Took Longer Than I Expected

The guide includes screenshots of the actual interface, covering code folding, error locations, JSON comparisons, queries, conversions, and settings.

At first, I thought I could just open the application and take a few screenshots. It turned out they needed some preparation.

A wide window makes the text too small when the image is placed in a document. Too much empty space makes the relevant part harder to spot. And if the query field is too narrow to show anything except the last few characters of an expression, the screenshot isn’t much help.

I adjusted the views to show the relevant data and results together. In the folding screenshot, I kept the line numbers visible so readers could see that the collapsed content was still there, just hidden.

Some Notes Belong Beside the Instructions

While putting the guide together, I made sure to explain a few things that are easy to miss.

History, for example, doesn’t save the original JSON content by default. Recording an operation doesn’t mean you can close an unsaved tab and recover the entire document later.

Sorting arrays changes their element order. That may be fine for a user list, but message logs and execution steps shouldn’t be reordered casually.

JSONC needs an explanation, too. Files with comments can be viewed, but formatting removes those comments and requires confirmation. The tool’s JSON Schema support also has limits, so warnings need to be read alongside validation results.

If those notes were all placed at the end, many readers might never reach them. Beside the relevant steps, there’s a better chance they’ll be seen before someone clicks a button.

Twelve Chapters in the Finished Guide

The first chapters cover everyday tasks: editing, validation, folding, and search. Later chapters introduce data comparisons, JSONPath, format conversion, schemas, statistics, and test data generation.

The guide is available on the project’s GitHub wiki. The link is at the end of this article.

Writing it made me look at the tool again. After using something often enough, you stop thinking about where to click next. Explaining those steps to someone else makes you notice whether a control is easy to find and whether its label says enough.

The guide is ready for now. I’ll keep using the tool for API responses and logs, and update the relevant chapters as the application changes.

Read the guide on GitHub: User Guide