Skip to main content

Documentation Maintenance

This guide describes the process for keeping backend development documentation up to date and provides templates for future additions.

Update Process​

1. Identifying Necessary Changes​

Documentation changes may arise from:

  • Changes in team practices
  • New tools or technologies adopted
  • Team feedback on clarity or completeness
  • Updates to CI/CD or deployment processes

2. Update Workflow​

  1. Create Branch: Create a specific branch for documentation updates

    git checkout -b docs/update-backend-guidelines

  2. Make Changes: Edit the corresponding markdown files in docs/backend/development-guidelines/

  3. Validate Locally: Run Docusaurus locally to verify changes

    npm run start

  4. Code Review: Create pull request following the same process as for code

    • At least one technical reviewer
    • Verify that changes are accurate and clear
    • Confirm there are no broken links

  5. Deploy: Once approved, merge and automatic deployment

3. Responsibilities​

  • Tech Lead: Approve significant process changes
  • Senior Developers: Technical review of content
  • Entire Team: Suggest improvements and report inconsistencies

Templates for New Sections​

Template for New Development Guide​

---
sidebar_position: [NUMBER]
title: [GUIDE TITLE]
description: [BRIEF DESCRIPTION]
---

# [Guide Title]

## Introduction

[Brief description of the purpose of this guide]

## Key Concepts

### [Concept 1]
[Concept explanation]

### [Concept 2]
[Concept explanation]

## Implementation

### Step 1: [Description]
[Detailed instructions]

```bash
# Command example if applicable

Step 2: [Description]​

[Detailed instructions]

Examples​

Correct Example​

// Code example

Incorrect Example​

// Code example of what NOT to do
  • [Tool 1]: [Description and usage]
  • [Tool 2]: [Description and usage]

References​

  • [Link to external documentation]
  • [Link to additional resources]

### Template for Existing Guide Update

```markdown
## Update Checklist

- [ ] Review outdated information
- [ ] Update code examples
- [ ] Verify external links
- [ ] Update recommended tools
- [ ] Review screenshots (if applicable)
- [ ] Validate that commands work
- [ ] Verify consistency with other guides

Quality Standards​

Content​

  • Clarity: Use clear and direct language
  • Completeness: Cover all necessary aspects
  • Currency: Keep information up to date
  • Consistency: Use consistent terminology

Format​

  • Front Matter: Include sidebar_position, title, and description
  • Structure: Use appropriate hierarchical headers
  • Code: Use appropriate syntax highlighting
  • Links: Verify that all links work

Examples​

  • Realistic: Use real-world examples
  • Complete: Include sufficient context
  • Current: Keep examples updated with current practices

Review Process​

Approval Criteria​

  1. Technical Accuracy: Content is technically correct
  2. Clarity: Information is easy to understand
  3. Completeness: Covers all necessary aspects
  4. Consistency: Maintains consistency with the rest of the documentation

Review Checklist​

  • Technically accurate content
  • Examples work correctly
  • Links are not broken
  • Correct markdown format
  • Navigation works correctly
  • Responsive design is maintained

Scheduled Maintenance​

Quarterly Review​

  • Review all guides to identify outdated content
  • Update mentioned tools and versions
  • Verify that processes remain relevant

Annual Review​

  • Complete evaluation of documentation structure
  • Identify gaps in documentation
  • Plan new sections or reorganization

Metrics and Feedback​

Quality Indicators​

  • Frequency of updates
  • Team feedback on usefulness
  • Onboarding time for new developers

Feedback Channels​

  • Repository issues to report problems
  • Team retrospectives for suggestions
  • Periodic surveys on documentation usefulness