Documentation Style Guide

This style guide provides standards and guidelines for writing and formatting documentation for the DeepLint project. Following these guidelines ensures consistency across all documentation files and improves readability for users.

Document Structure

File Organization

Each documentation file should follow this general structure:

1. Title: A clear, descriptive title using a single H1 (#) heading

2. Introduction: A brief overview of what the document covers

3. Main Content: The primary content of the document, organized into logical sections

4. Related Resources: Links to related documentation

5. Next Steps (optional): Suggestions for what to read or do next

Example:

# Feature Name

Brief introduction to the feature and what it does.

## Overview

More detailed explanation of the feature.

## Usage

How to use the feature.

## Configuration

How to configure the feature.

## Related Resources

- [Related Document 1](path/to/document1.md)
- [Related Document 2](path/to/document2.md)

## Next Steps

- [Next Step 1](path/to/next-step1.md)
- [Next Step 2](path/to/next-step2.md)

Heading Hierarchy

Use a consistent heading hierarchy:

• # (H1): Document title (only one per document)

• ## (H2): Major sections

• ### (H3): Subsections

• #### (H4): Sub-subsections (use sparingly)

Do not skip heading levels (e.g., don't go from H2 to H4 without an H3 in between).

Navigation Hints

For documents that are part of a series, include navigation hints at the top and bottom:

<div data-gb-custom-block data-tag="hint" data-style='info'>

This is part of the Getting Started series:

1. [Installation](installation.md)
2. **Configuration** (current page)
3. [First Run](first-run.md)
4. [Git Integration](git-integration.md)
   

</div>

At the bottom of the document, include navigation links:

---

**Previous**: [Installation](installation.md) | **Next**: [First Run →](first-run.md)

Content Formatting

Text Formatting

• Use bold (**bold**) for emphasis and UI elements

• Use italic (*italic*) for introducing new terms

• Use code (`code`) for code snippets, file names, and commands

• Use > blockquotes for important notes or quotes

Lists

• Use unordered lists (-) for items without a specific order

• Use ordered lists (1., 2., etc.) for sequential steps or prioritized items

• Maintain consistent indentation for nested lists (2 spaces)

Code Blocks

• Use triple backticks (```) for code blocks

• Specify the language for syntax highlighting (e.g., ```typescript)

• For terminal commands, use ```bash and include the command prompt ($) for clarity

Example:

```typescript
function example(): void {
  console.log("Hello, world!");
}
```

```bash
$ deeplint init
```

Tables

Use tables for structured data:

| Column 1 | Column 2 | Column 3 |
| -------- | -------- | -------- |
| Value 1  | Value 2  | Value 3  |
| Value 4  | Value 5  | Value 6  |

Hints and Callouts

Use GitBook hint blocks for important information:

<div data-gb-custom-block data-tag="hint" data-style='info'>

This is an informational note.

</div>

<div data-gb-custom-block data-tag="hint" data-style='warning'>

This is a warning.

</div>

<div data-gb-custom-block data-tag="hint" data-style='success'>

This is a success message or tip.

</div>

<div data-gb-custom-block data-tag="hint" data-style='danger'>

This is a danger or error message.

</div>

Tabs

Use GitBook tabs for alternative approaches or examples:

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

<div data-gb-custom-block data-tag="tab" data-title='JavaScript'>

```javascript
const example = () => {
  console.log("Hello, world!");
};
```

const example = (): void => {
  console.log("Hello, world!");
};

## Diagrams and Visual Elements

### Mermaid Diagrams

Use Mermaid diagrams for flowcharts, sequence diagrams, and other visual representations:

```markdown

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

graph TD
A[Start] --> B[Process]
B --> C[End]

</div>

Keep diagrams simple and focused on the key concepts. Include a text explanation of the diagram for accessibility.

Images

When including images:

• Use descriptive file names

• Include alt text for accessibility

• Keep images in an assets directory

• Optimize images for web viewing

![Alt text describing the image](assets/image-name.png)

Content Guidelines

Voice and Tone

• Use a clear, direct, and professional tone

• Write in the present tense

• Use active voice instead of passive voice

• Address the reader directly using "you"

Terminology

• Use consistent terminology throughout the documentation

• Define technical terms when they are first introduced

• Follow the project's glossary for specific terms

Examples

• Include practical, real-world examples

• Ensure examples are accurate and tested

• Provide context for examples

• Use consistent formatting for examples

Command Line Examples

When documenting command line usage:

• Include the command and its output

• Use $ to indicate the command prompt

• Use # for comments within command blocks

• Show example output when relevant

```bash
# Initialize DeepLint
$ deeplint init

# Output:
# DeepLint initialized successfully!
# Configuration file created at: /path/to/deeplint.config.js
```

### Configuration Examples

When documenting configuration options:

- Show both JavaScript and YAML examples when applicable
- Include comments explaining each option
- Show default values
- Provide complete, working examples

## Cross-References

### Internal Links

Use relative links for internal documentation:

```markdown
See the [Configuration](../getting-started/configuration.md) guide for more information.

External Links

For external links, include the full URL and a descriptive link text:

For more information, see the [TypeScript Documentation](https://www.typescriptlang.org/docs/).

Versioning and Status Indicators

Version Information

Indicate when features are version-specific:

<div data-gb-custom-block data-tag="hint" data-style='info'>

This feature is available in DeepLint v1.2.0 and later.

</div>

Feature Status

Clearly mark the status of features:

• ✅ Implemented: Feature is fully implemented and available

• ⚠️ Partial: Feature is partially implemented

• 🚧 Planned: Feature is planned but not yet implemented (see Roadmap)

Example:

| Feature         | Status         | Description                                                                |
| --------------- | -------------- | -------------------------------------------------------------------------- |
| Context Builder | ✅ Implemented | Builds context for analysis                                                |
| LLM Integration | 🚧 Planned     | Integrates with LLM providers (see [Roadmap](developer/roadmap/mvp-v1.md)) |

Accessibility

• Use descriptive link text (not "click here" or "read more")

• Include alt text for images

• Ensure color is not the only way to convey information

• Use proper heading hierarchy for screen readers

File Naming

• Use lowercase for file names

• Use hyphens (-) instead of spaces or underscores

• Use descriptive, concise names

• Group related files in directories

Examples:

• getting-started.md

• command-system.md

• context-building.md

Implementation Guidelines

When implementing this style guide:

1. Start with high-visibility documents (README, Getting Started guides)

2. Update one section of documentation at a time

3. Use search and replace for consistent terminology

4. Verify links after making changes

5. Test code examples to ensure they work

Applying the Style Guide

When applying this style guide to existing documentation:

1. Structure: Ensure each document follows the recommended structure

2. Headings: Verify heading hierarchy is consistent

3. Formatting: Apply consistent formatting for code, lists, tables, etc.

4. Examples: Update examples to follow the guidelines

5. Cross-References: Check and update all internal and external links

6. Status Indicators: Add status indicators for features

7. Navigation: Add navigation hints for document series

Conclusion

Following this style guide ensures a consistent, high-quality documentation experience for DeepLint users. If you have questions or suggestions for improving this guide, please open an issue or pull request.