Documentation Guide

docs/ Folder Organization

The Shirinzad project uses a well-organized documentation structure divided into several key directories:

Documentation Workflow

1. Identify Documentation Needs
   • New features require documentation
   • Update docs when changing existing features
   • Fix outdated or incorrect information
   • Add missing examples or clarifications
2. Choose the Right Location
   • API changes → docs/api/
   • Architecture changes → docs/project/
   • How-to guides → docs/guides/
   • Development practices → docs/development/
3. Follow Documentation Standards
   • Use clear, concise language
   • Include code examples
   • Add diagrams where helpful
   • Keep formatting consistent
4. Review and Update
   • Test all code examples
   • Review for accuracy and clarity
   • Update table of contents if needed
   • Submit for peer review

Markdown Conventions

Document Template Structure

# Document Title

## Overview
Brief description of the document's purpose and scope.

## Table of Contents
- [Section 1](#section-1)
- [Section 2](#section-2)
- [Section 3](#section-3)

## Section 1
Content with examples...

### Subsection 1.1
Detailed information...

## Code Examples
```csharp
// Well-commented code example
public class ExampleService
{
    // Implementation
}
```

## Related Documentation
- [Related Doc 1](link)
- [Related Doc 2](link)

## Last Updated
**Date:** 2025-01-04
**Author:** Developer Name
**Version:** 1.0.0

C# XML Documentation Standards

All public APIs must have XML documentation comments for automatic documentation generation.

/// <summary>
/// Retrieves a product by its unique identifier.
/// </summary>
/// <param name="id">The unique identifier of the product.</param>
/// <returns>A task that represents the asynchronous operation. The task result contains the product DTO.</returns>
/// <exception cref="EntityNotFoundException">Thrown when the product is not found.</exception>
/// <example>
/// <code>
/// var product = await _productService.GetAsync(123);
/// </code>
/// </example>
public async Task<ProductDto> GetAsync(int id)
{
    // Implementation
}

Required XML Tags

API Documentation with Swagger Attributes

Use Swagger annotations to enhance API documentation with examples, descriptions, and response types.

/// <summary>
/// Creates a new product
/// </summary>
/// <param name="input">Product creation data</param>
/// <returns>The newly created product</returns>
[HttpPost]
[ProducesResponseType(typeof(ProductDto), StatusCodes.Status201Created)]
[ProducesResponseType(typeof(ErrorResponse), StatusCodes.Status400BadRequest)]
[ProducesResponseType(typeof(ErrorResponse), StatusCodes.Status401Unauthorized)]
[SwaggerOperation(
    Summary = "Create a new product",
    Description = "Creates a new product with the provided information. Requires admin role.",
    Tags = new[] { "Products" }
)]
public async Task<ActionResult<ProductDto>> CreateAsync(CreateProductDto input)
{
    var result = await _productService.CreateAsync(input);
    return CreatedAtAction(nameof(GetAsync), new { id = result.Id }, result);
}

Swagger Configuration Best Practices

• Include XML comments file in Swagger configuration
• Use [ProducesResponseType] for all possible responses
• Add [SwaggerOperation] for detailed descriptions
• Group endpoints with Tags
• Provide example request/response bodies
• Document authentication requirements
• Include deprecation notices for outdated endpoints

Standard README Template

# Project Name

## Description
Brief project description and purpose.

## Features
- Feature 1
- Feature 2
- Feature 3

## Prerequisites
- .NET 9.0 SDK
- SQL Server 2019+
- Redis (optional)

## Installation

### Clone the Repository
```bash
git clone https://github.com/shirinzad/backend.git
cd backend
```

### Configuration
1. Update `appsettings.json`
2. Configure connection strings
3. Set up Redis (if using)

### Database Setup
```bash
dotnet ef database update
```

### Run the Application
```bash
dotnet run --project src/Shirinzad.Shop.HttpApi.Host
```

## Usage
Examples of how to use the application...

## API Documentation
- Swagger UI: `https://localhost:5001/swagger`
- API Docs: [docs/api/](docs/api/)

## Testing
```bash
dotnet test
```

## Deployment
See [DEPLOYMENT_GUIDE.md](DEPLOYMENT_GUIDE.md)

## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md)

## License
[License Type]

## Contact
- Email: [email protected]
- Website: https://shirinzad.ir

AI-Friendly Documentation

The CLAUDE.md file provides structured information for AI assistants like Claude to understand the project quickly.

# Shirinzad E-Commerce Platform - AI Assistant Guide

## Project Overview
- **Type:** E-Commerce Backend
- **Framework:** .NET 9.0 + ABP.io 9.3.5
- **Architecture:** Domain-Driven Design (DDD)
- **Database:** SQL Server + Redis Cache

## Project Structure
```
src/
├── Shirinzad.Shop.Domain/          # Domain entities, repositories
├── Shirinzad.Shop.Application/     # Application services, DTOs
├── Shirinzad.Shop.HttpApi/         # API controllers
├── Shirinzad.Shop.HttpApi.Host/    # API hosting
├── Shirinzad.Shop.EntityFrameworkCore/ # EF Core, migrations
└── Shirinzad.Shop.Web/             # Web UI (Razor Pages)
```

## Key Conventions
- All services inherit from `ApplicationService`
- DTOs use AutoMapper for entity mapping
- Repositories follow ABP repository pattern
- Authorization uses ABP permission system
- Validation uses Data Annotations + FluentValidation

## Common Tasks

### Adding a New Entity
1. Create entity in `Domain` project
2. Add to `DbContext` in `EntityFrameworkCore` project
3. Create migration: `Add-Migration AddEntityName`
4. Update database: `Update-Database`

### Adding a New Service
1. Create service interface in `Application.Contracts`
2. Implement service in `Application` project
3. Inherit from `ApplicationService`
4. Use `ObjectMapper` for DTO mapping

### Adding a New API Endpoint
1. Create controller in `HttpApi` project
2. Inherit from `ShopController`
3. Add XML documentation comments
4. Add Swagger attributes

## Testing Strategy
- Unit tests: `test/Shirinzad.Shop.Application.Tests/`
- Integration tests: `test/Shirinzad.Shop.TestBase/`
- Test framework: xUnit + Shouldly + NSubstitute

## Important Notes
- Always use async/await for I/O operations
- Follow SOLID principles
- Write XML documentation for public APIs
- Add unit tests for business logic
- Use DTOs for API boundaries
- Never expose domain entities directly

Other Documentation Tools

Documentation Maintenance Strategy

1. Documentation-First Approach

• Write or update documentation before implementing features
• Use documentation as design specification
• Review documentation during code review
• Treat docs as part of the Definition of Done

2. Automated Checks

• Enforce XML comments on public APIs (StyleCop rules)
• Check for broken links in markdown files
• Validate code examples in documentation
• Run documentation builds in CI/CD pipeline

3. Regular Review Schedule

4. Documentation Metrics

• API documentation coverage (XML comments)
• Number of outdated documentation issues
• Time since last documentation update
• User feedback on documentation quality

Review Checklist

Content Review

• Accuracy: Information is correct and up-to-date
• Completeness: All necessary information is included
• Clarity: Easy to understand for target audience
• Consistency: Follows documentation standards
• Examples: Code examples are working and relevant

Technical Review

• Code examples compile and run
• API signatures match implementation
• Links are not broken
• Images and diagrams are visible
• Version information is correct

Style Review

• Follows markdown conventions
• Proper heading hierarchy
• Consistent formatting and indentation
• Correct spelling and grammar
• Appropriate tone and voice

Accessibility Review

• Alt text for images
• Descriptive link text
• Proper table headers
• Clear and logical structure
• No color-only information

Writing Guidelines

Voice and Tone

• Be Clear: Use simple, direct language
• Be Concise: Avoid unnecessary words
• Be Consistent: Use consistent terminology
• Be Professional: Maintain professional tone
• Be Helpful: Anticipate reader questions

Terminology Standards

Formatting Standards

• Code: Use `backticks` for inline code
• Commands: Use code blocks with language specification
• File Paths: Use `backticks` for file paths
• UI Elements: Use bold for button names
• Emphasis: Use italics for emphasis (sparingly)
• Variables: Use <angle_brackets> in examples

Visual Documentation Best Practices

When to Use Visuals

• UI Documentation: Screenshots of user interfaces
• Architecture: System architecture diagrams
• Workflows: Flowcharts for complex processes
• Data Models: ER diagrams for database schemas
• Sequences: Sequence diagrams for interactions

Screenshot Guidelines

• Use consistent resolution (1920x1080 or higher)
• Crop to relevant area only
• Highlight important areas with annotations
• Save in PNG format for quality
• Store in docs/images/ directory
• Use descriptive filenames: product-list-page.png

Diagram Tools

Example: Mermaid Diagram in Markdown

```mermaid
sequenceDiagram
    participant Client
    participant API
    participant Database

    Client->>API: POST /api/products
    API->>Database: Insert Product
    Database-->>API: Product Created
    API-->>Client: 201 Created
```

External Resources

• Write the Docs - Documentation community
• Google Developer Documentation Style Guide
• Microsoft Writing Style Guide
• Markdown Guide
• Mermaid.js Documentation
• Swagger/OpenAPI Documentation
• DocFX Documentation
• MkDocs Documentation