Spanish Documentation Standards

Generate and maintain comprehensive technical documentation following Spanish conventions with strict standards for architecture, API endpoints, and technical specifications.

Instructions

1. Graph and Visualization Output

When generating graphs or visualizations from any script:

**Default format**: Always output as SVG (.svg) unless technically impossible

**Alternative formats**: Only use other formats when SVG is not feasible

**Justification**: If using non-SVG format, document the technical reason in the script or documentation

2. Documentation Structure

Create and maintain the following directory structure:

```

project-root/

├── README.md (main project overview)

├── documentacion/

│ ├── {subproject-1}/

│ │ ├── README.md

│ │ ├── arquitectura.md

│ │ ├── definicion_tecnica.md

│ │ └── endpoints.md (for APIs)

│ └── {subproject-2}/

│ ├── README.md

│ ├── arquitectura.md

│ ├── definicion_tecnica.md

│ └── endpoints.md (for APIs)

```

3. Required Documents per Subproject

For each subproject in `documentacion/{subproyecto}/`, create:

**README.md**

General description of the subproject

Purpose and goals

Directory structure

Quick start guide

**arquitectura.md**

Detailed architectural design

System components and relationships

Data flow diagrams (use Mermaid)

Technology stack decisions

**definicion_tecnica.md**

Exhaustive technical specification

Abstract enough to rebuild in another technology

Technical requirements

Configuration details

Deployment specifications

**endpoints.md** (for APIs only)

Complete endpoint documentation

Follow the standard format below

4. API Endpoint Documentation Standard

For each endpoint in `endpoints.md`, use this mandatory structure:

```markdown

X.Y Endpoint Name

**HTTP_METHOD** `/route/path`

Brief description of the endpoint's purpose.

#### Headers

```

Authorization: Bearer <token>

Content-Type: application/json

```

#### Query Parameters (if applicable)

`param1`: Description

`param2`: Description

#### Request Body

```json

{

"field": "value",

"required_field": "example"

}

```

#### Successful Response (200/201)

```json

{

"success": true,

"data": {

"id": "123",

"field": "value"

}

```

#### Error Response (400)

```json

{

"success": false,

"message": "Error description",

"errors": []

}

```

#### Error Response (401)

```json

{

"success": false,

"message": "Unauthorized"

}

```

#### Error Response (403)

```json

{

"success": false,

"message": "Forbidden"

}

```

#### Error Response (404)

```json

{

"success": false,

"message": "Resource not found"

}

```

#### Error Response (422)

```json

{

"success": false,

"message": "Validation error",

"errors": []

}

```

#### Error Response (500)

```json

{

"success": false,

"message": "Internal server error"

}

```

#### Endpoint Characteristics

**Authentication**: Required/Not required (specify roles if applicable)

**Permissions**: Specific roles if applicable

**Validation**: Types of validation applied

**Transactional**: Whether it uses database transactions

**Rate Limiting**: Specific limits if applicable

```

5. Mandatory Sections in endpoints.md

Include these sections:

1. **General Information**

- Base URL

- Authentication methods

- Response formats

- Versioning

2. **Endpoints by Functionality**

- Authentication

- Users

- Resources (grouped logically)

3. **Error Codes**

- HTTP status codes

- System-specific error codes

- Error message formats

4. **Usage Examples**

- Complete workflow examples

- Common use cases

- Integration examples

5. **Navigation**

- Links to related documentation

- Cross-references

6. Documentation Standards

**Format**: Use Markdown for all documents

**Diagrams**: Include when necessary (prefer Mermaid)

**Code Examples**: Keep updated and functional

**Interlinks**: All documents must be interconnected

**Navigation**: Maintain coherent navigation between documents

**Cross-references**: Use when appropriate

**Inline Documentation**: Comment complex code

7. Git and Version Control Rules

**CRITICAL - Pre-Commit Checks**:

Before committing endpoint changes, verify documentation is updated

Include updated documentation in the same commit as code changes

If accepting a new feature, update documentation THEN commit

**General Git Rules**:

Use descriptive commits (up to 255 characters)

Follow branching conventions

Keep .gitignore updated

Never commit sensitive files

8. Performance Considerations

When documenting APIs and systems:

Document database query optimizations

Specify caching strategies where appropriate

Note performance monitoring requirements

Minimize unnecessary dependencies

Example Usage

When creating a new API endpoint:

1. Implement the endpoint code

2. Before committing, create/update `endpoints.md` with full documentation

3. Ensure all error responses are documented

4. Add authentication and permission requirements

5. Include example requests and responses

6. Commit code and documentation together

When creating a new subproject:

1. Create directory structure: `documentacion/{subproject}/`

2. Generate all required documents: README.md, arquitectura.md, definicion_tecnica.md

3. Add API documentation if applicable

4. Interlink all documents

5. Update main project README.md

Constraints

Documentation must be in Spanish

SVG is mandatory for graphs unless technically impossible

Endpoint documentation must include ALL possible error responses

Code commits without updated documentation are not allowed

All technical specifications must be abstract enough for technology-agnostic reconstruction

Spanish Documentation Standards

Spanish Documentation Standards

Instructions

1. Graph and Visualization Output

2. Documentation Structure

3. Required Documents per Subproject

4. API Endpoint Documentation Standard

X.Y Endpoint Name

5. Mandatory Sections in endpoints.md

6. Documentation Standards

7. Git and Version Control Rules

8. Performance Considerations

Example Usage

Constraints

Reviews (0)