Readability Guidelines

This document provides guidelines for improving the readability of DeepLint documentation. Following these guidelines ensures that documentation is accessible, engaging, and easy to understand for all users.

General Principles

User-Centric Approach

• Focus on the user's needs and goals

• Organize content based on user tasks rather than system architecture

• Consider different user personas (beginners, experienced developers, etc.)

• Anticipate common questions and provide answers

Plain Language

• Use clear, concise language

• Avoid unnecessary technical jargon

• Define technical terms when they must be used

• Use active voice and present tense

• Keep sentences and paragraphs short

Visual Hierarchy

• Use headings and subheadings to create a clear structure

• Use lists and tables to organize information

• Use whitespace effectively

• Highlight important information

Reducing Technical Jargon

Identifying Jargon

Technical jargon includes:

• Acronyms and abbreviations

• Domain-specific terminology

• Internal project terminology

• Complex technical concepts

When to Use Technical Terms

Use technical terms when:

• The term is widely understood by the target audience

• The term is necessary for precision

• The term is defined when first introduced

• There is no simpler alternative

When to Avoid Technical Terms

Avoid technical terms when:

• A simpler alternative exists

• The term is not essential for understanding

• The term is internal jargon not familiar to users

• The documentation is aimed at beginners

Examples of Jargon Replacement

Technical Term	Plain Language Alternative
"Utilize"	"Use"
"Implement"	"Create" or "Build"
"Instantiate"	"Create"
"Terminate"	"End" or "Stop"
"Functionality"	"Feature"
"LLM Context"	"Code Analysis Context"

Before and After Examples

Before (With Jargon)

To utilize the context builder, instantiate a ContextBuilder object and invoke the buildContext method. The method returns a Promise that resolves to a ContextBuildResult object containing the LLM context and associated metadata.

After (Without Jargon)

To use the context builder, create a ContextBuilder object and call the buildContext method. This method returns a Promise with the analysis results and related information.

Adding Practical Examples

Types of Examples

Include different types of examples:

• Basic examples: Simple, focused examples for beginners

• Common use cases: Examples that solve real-world problems

• Advanced examples: More complex examples for experienced users

• Troubleshooting examples: Examples that show how to fix common issues

Example Structure

Structure examples consistently:

1. Context: Explain when and why to use this approach

2. Code: Show the example code

3. Explanation: Explain what the code does

4. Result: Show the expected output or result

5. Variations: Show alternative approaches (optional)

Example: Adding Examples to Documentation

Basic Example

### Basic Usage

To analyze staged changes in your Git repository:

```bash
deeplint
```

This command will analyze the files you've staged with git add and show any issues found.

Output:

INFO: Running DeepLint on staged changes...
INFO: Context built with 3 changed files
INFO: Analysis complete: No issues found

#### Common Use Case Example

```markdown
### Analyzing Specific Files

If you want to analyze specific files instead of staged changes:

```bash
deeplint --unstaged src/main.ts src/utils.ts

This is useful when you want to check files before staging them or when working on specific parts of your codebase.

Output:

INFO: Running DeepLint on specified files...
INFO: Context built with 2 files
INFO: Analysis complete: 1 issue found
WARN: Potential issue in src/utils.ts:42 - Unused variable 'config'

## Improving Visual Elements

### Diagrams

Use diagrams to explain:

- Workflows and processes
- System architecture
- Relationships between components
- Concepts that are difficult to explain in text

#### Diagram Best Practices

- Keep diagrams simple and focused
- Use consistent colors and shapes
- Include a legend if necessary
- Provide a text explanation alongside the diagram
- Use Mermaid for diagrams that can be maintained in Markdown

#### Example: Workflow Diagram

```markdown

<div data-gb-custom-block data-tag="mermaid">

graph TD
A[Stage Changes] -->|git add| B[Run DeepLint]
B --> C{Issues Found?}
C -->|Yes| D[Review Issues]
D --> E[Fix Issues]
E --> A
C -->|No| F[Commit Changes]

</div>

This diagram shows the typical workflow when using DeepLint with Git:

1. Stage your changes using `git add`
2. Run DeepLint to analyze the staged changes
3. If issues are found, review and fix them, then stage the fixes
4. If no issues are found, commit your changes

Tables

Use tables to present:

• Comparison of options or features

• Configuration settings

• Command line arguments

• Structured data

Table Best Practices

• Use clear column headers

• Align content for readability

• Keep tables simple (avoid nested tables)

• Use consistent formatting

• Provide context before the table

Example: Command Options Table

| Option       | Description                   | Default | Example               |
| ------------ | ----------------------------- | ------- | --------------------- |
| `--context`  | Context depth (light or deep) | `light` | `--context=deep`      |
| `--unstaged` | Include unstaged changes      | `false` | `--unstaged`          |
| `--debug`    | Enable debug output           | `false` | `--debug`             |
| `--dump`     | Dump context to a file        | -       | `--dump=context.json` |

Screenshots and Images

Use screenshots and images to show:

• UI elements and interactions

• Expected output

• Visual concepts

• Step-by-step processes

Image Best Practices

• Use clear, high-quality images

• Crop images to focus on relevant content

• Add annotations or highlights when necessary

• Include alt text for accessibility

• Optimize images for web viewing

Example: Screenshot with Annotation

![DeepLint output showing an issue with an unused variable](assets/deeplint-output.png)

_Figure 1: DeepLint output highlighting an unused variable in src/utils.ts_

Implementation Guidelines

When implementing these readability improvements:

1. Start with user-facing documentation (Getting Started guides, README, etc.)

2. Focus on one section at a time to maintain consistency

3. Test with different audiences to ensure clarity

4. Update examples when the API or behavior changes

5. Use the style guide to maintain consistent formatting

Checklist for Enhancing Readability

Use this checklist when reviewing documentation for readability:

• Is the content organized based on user tasks?

• Is the language clear and concise?

• Are technical terms defined when first introduced?

• Are there sufficient examples for common use cases?

• Are visual elements used effectively?

• Is the content accessible to the target audience?

• Is the formatting consistent with the style guide?

Conclusion

By following these guidelines, we can create documentation that is more readable, accessible, and helpful for all users. Remember that the goal of documentation is to help users understand and use DeepLint effectively, regardless of their technical background or experience level.