Documentation Standards for JSON Formatting Tools

1. Getting Started / Quick Start Guide

This section should provide a very brief overview of how to use the tool for its primary function: pasting or loading JSON and formatting it.

1. Open the tool in your browser.
2. Paste your JSON data into the input area.
3. Click the "Format" button.
4. View the formatted JSON in the output area.

Include screenshots or simple diagrams if possible.

2. Basic Usage and Interface Description

A more detailed look at the tool's interface.

• Describing input and output areas.
• Explaining buttons and their functions (e.g., Format, Minify, Validate, Clear, Copy).
• How to load JSON from a file (if supported).
• How to save the output.

3. Features and Options

Detailing all the functionalities beyond basic formatting.

• Validation: Explain how the tool validates JSON against the spec, what errors it checks for, and how errors are reported.
• Minification: Describe how it removes whitespace and comments (if supported) to reduce file size.
• Sorting: If keys can be sorted alphabetically, explain how this works and any limitations (e.g., object keys only).
• Conversion: If the tool converts JSON to other formats (like XML, CSV, YAML), provide detailed instructions and potential issues.
• Specific Formatting Options:
  • Indentation style (spaces vs. tabs, number of spaces).
  • Control over spacing around colons, commas, brackets.
  • Handling of empty arrays or objects.

Example documentation snippet for Indentation Option:

Indentation:
Select the character(s) used for indentation.

- **2 Spaces:** Uses two space characters (` `) for each level of indentation. Recommended for readability.
- **4 Spaces:** Uses four space characters (`    `). A common standard in many projects.
- **Tab:** Uses a tab character (`\t`). Tab width may vary based on your editor.

4. Error Handling and Troubleshooting

Clearly explaining what happens when invalid JSON is input.

• Types of errors detected (syntax, invalid values, etc.).
• How errors are displayed (line numbers, highlighting, error messages).
• Common error messages and their meaning (e.g., "Unexpected token {character} at position {number}").
• Tips for debugging JSON syntax errors.

Example error explanation:

<span className="font-medium text-red-600 dark:text-red-400">Error: Trailing comma not allowed</span>
**Meaning:** You have placed a comma after the last element in an array or object.
**JSON does NOT** allow a comma after the final item in a list.
**Correct:** `["apple", "banana"]`
**Incorrect:** `["apple", "banana",]`

Check the line number indicated by the tool and remove the extra comma.

5. Supported JSON Specification

Mentioning which JSON standard or specification the tool adheres to. This is particularly important if the tool has unique behaviors or supports variations like JSONC (JSON with Comments) or JSON5.

6. Accessibility and Usability Features

Highlighting features that improve the user experience for a wider audience.

• Keyboard shortcuts.
• Support for screen readers.
• Theme options (light/dark mode).
• Handling of large files (performance notes).

7. Privacy and Offline Usage

For tools designed for offline use, clearly stating that data is processed locally in the browser is crucial for user privacy and security confidence.

**Data Privacy:** Your JSON data is processed entirely within your browser. It is **never** sent to
any server. You can use this tool offline after the initial load.

Good Example of Documenting an Option:

Clearly show the option name, describe its purpose, and provide before/after examples.

Option: Sort Object Keys Alphabetically

When enabled, this option will sort the keys within every JSON object alphabetically. This helps in standardizing JSON output and making it easier to compare different JSON objects.

Default: Off

Effect:

{
  "zip": "12345",
  "name": "Example",
  "id": 101
}

{
  "id": 101,
  "name": "Example",
  "zip": "12345"
}