Document writing and maintenance standards

Documentation Writing and Maintenance Standards

Documentation is an indispensable part of the software development process. Well-defined documentation writing and maintenance standards can improve team collaboration efficiency, reduce communication costs, and ensure sustainable project development. The following elaborates on how to establish an effective documentation system from multiple dimensions.

Documentation Types and Structure

Technical documentation is typically categorized into the following types:

1. API Documentation: Describes interface parameters, return values, error codes, etc.
2. Architecture Design Documentation: Explains the overall system design approach.
3. User Guides: Operation manuals for end users.
4. Developer Manuals: Technical details for developers.

Standard documentation structure example:

# Document Title  

## Overview  
Briefly describe the purpose and scope of the document.  

## Feature Description  
Detail the functional features.  

## Interface Definition  
- Request Method: GET/POST/PUT/DELETE  
- Request Parameters:  
  ```json  
  {  
    "param1": "value1",  
    "param2": 123  
  }  

• Response Example:

  {  
    "code": 200,  
    "data": {}  
  }  
  

## Documentation Writing Guidelines  

### Language Style  
- Use concise and clear sentences.  
- Avoid long paragraphs; limit each paragraph to no more than 5 lines.  
- Provide explanations for technical terms when they first appear.  

### Formatting Requirements  
1. Limit heading levels to no more than 4.  
2. Specify the language type for code blocks.  
3. Use standard Markdown syntax for tables.  

Example table:  

| Parameter | Type | Required | Description |  
|----------|------|---------|------------|  
| userId | string | Yes | Unique user identifier |  
| pageSize | number | No | Items per page, default 10 |  

### Version Control  
Each document should include version information at the top:  

```markdown  
---  
version: 1.0.2  
update: 2023-08-15  
author: dev-team  
---  

Documentation Maintenance Process

Change Management

1. Any modifications require a Pull Request.
2. Must be reviewed by at least one core team member.
3. Major changes must be discussed in a team meeting.

Automated Checks

Configure ESLint to check Markdown syntax:

// .eslintrc.js  
module.exports = {  
  plugins: ['markdown'],  
  extends: [  
    'plugin:markdown/recommended'  
  ]  
}  

Regular Audits

• Check outdated documents on the first working day of each month.
• Move deprecated API documentation to the archive directory.
• Use scripts to automatically detect dead links:

# Check for invalid links in documents  
npm run check-links  

Toolchain Configuration

Recommended documentation toolset:

1. Writing Tools: VS Code + Markdown All in One plugin.
2. Collaboration Platform: GitBook or Confluence.
3. Visualization: Mermaid diagram support.

Example sequence diagram:

sequenceDiagram  
    participant User  
    participant Frontend  
    participant Backend  
      
    User->>Frontend: Submit form  
    Frontend->>Backend: POST /api/submit  
    Backend-->>Frontend: Return 201  
    Frontend-->>User: Show success message  

Quality Evaluation Metrics

Establish a documentation quality scoring system:

1. Completeness (40%): Covers all key points.
2. Accuracy (30%): Information matches the code.
3. Readability (20%): Language is clear and easy to understand.
4. Timeliness (10%): Updated promptly.

Scoring example:

function evaluateDoc(doc) {  
  const { completeness, accuracy, readability, timeliness } = doc;  
  return completeness * 0.4 +   
         accuracy * 0.3 +   
         readability * 0.2 +   
         timeliness * 0.1;  
}  

Team Collaboration Agreements

1. New members must read core documentation during onboarding.
2. Code commits must be linked to documentation updates.
3. Implement a rotating documentation maintenance system.

Git commit example:

feat(user): Add delete user interface  

- Added DELETE /users/:id endpoint  
- Updated API documentation section 3.2  

Close #123  

Localization Strategy

For international projects:

1. Main version is written in English.
2. Use JSON to manage multilingual content:

{  
  "docs": {  
    "login": {  
      "en": "User login",  
      "zh": "用户登录"  
    }  
  }  
}  

3. Automated translation workflow:

// Sync translation files automatically  
function syncTranslations() {  
  // Call translation API  
  // Generate multilingual documentation  
}  

Performance Optimization Suggestions

Optimization strategies for large documentation projects:

1. Split sub-documents and load on demand.
2. Implement full-text search functionality.
3. Compress static resources.

Search implementation example:

// Implement client-side search  
document.addEventListener('DOMContentLoaded', () => {  
  const index = new FlexSearch.Document({  
    document: {  
      id: "id",  
      index: ["h2", "h3", "p"]  
    }  
  });  
    
  // Add document content to index  
  index.add(document.body);  
});  

Security Considerations

1. Sensitive information must be redacted.
2. Set access permissions for internal documents.
3. Regularly review documents for leaked secrets.

Sensitive information filtering example:

# Scan before document publication  
def scan_secrets(text):  
    patterns = [  
        r'AKIA[0-9A-Z]{16}',  # AWS keys  
        r'sk_live_[0-9a-z]{32}' # Stripe keys  
    ]  
    for pattern in patterns:  
        if re.search(pattern, text):  
            raise SecurityError("Sensitive information detected")