Document writing standards

The Necessity of Engineering Standards

Engineering standards are the foundation of team collaboration. The lack of uniform standards can lead to chaotic code styles and increased maintenance costs. Taking CSS as an example, different developers may adopt varying naming conventions:

/* Developer A's style */
.main_content {}
.sideBar {}

/* Developer B's style */
.main-content {}
.side_bar {}

Such discrepancies can significantly reduce code readability in large-scale projects. Google's research data shows that teams adhering to unified standards experience an average 37% reduction in code review time.

Standardization of Documentation Structure

Project-Level Documentation

A hierarchical directory structure is recommended:

docs/
├── ARCHITECTURE.md     # Architectural design
├── API.md             # API documentation
├── CHANGELOG.md       # Change log
└── components/        # Component documentation
    └── Button.md

Single-File Comment Standards

JavaScript files should follow the JSDoc standard:

/**
 * Calculate discounted product price
 * @param {number} originalPrice - Original price
 * @param {number} discount - Discount rate (0-1)
 * @returns {number} Discounted price
 * @throws {Error} Throws an error for invalid discount rates
 */
function calculateDiscount(originalPrice, discount) {
  if (discount < 0 || discount > 1) {
    throw new Error('Invalid discount rate');
  }
  return originalPrice * (1 - discount);
}

Code Style Constraints

ESLint Configuration Example

.eslintrc.js should include team-customized rules:

module.exports = {
  rules: {
    'indent': ['error', 2],
    'quotes': ['error', 'single'],
    'react/prop-types': 'off',
    'max-len': ['error', { 
      code: 100,
      ignoreUrls: true 
    }]
  }
};

CSS Naming Standards

BEM naming methodology is recommended:

/* Block Element Modifier */
.search-form__input--disabled {
  opacity: 0.5;
  cursor: not-allowed;
}

Version Control Standards

Git Commit Messages

Adopt the Angular commit convention:

feat(authentication): add OAuth2 support

- Implement Google OAuth flow
- Add token refresh mechanism
- Update documentation

Closes #123

The type must be one of the following:

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• style: Code formatting
• refactor: Refactoring
• test: Test-related
• chore: Build process or auxiliary tool changes

Component Documentation Example

Vue components should include complete property definitions:

## Button Component

### Basic Usage
```vue
<Button type="primary">Submit</Button>

Props

Events

## Automated Documentation Generation

### TypeScript Interface Documentation
Use `typedoc` to generate API documentation:

```typescript
/**
 * User information interface
 * @remarks
 * Includes basic user data and permission information
 */
interface User {
  /**
   * Unique user ID
   * @format uuid
   */
  id: string;
  
  /** Display name */
  displayName: string;
  
  /** Permission level 1-10 */
  permissionLevel: number;
}

Documentation Checks in Continuous Integration

Add documentation validation to the CI pipeline:

# .github/workflows/docs.yml
steps:
  - name: Check docs
    run: |
      npx doctoc --check README.md
      npx markdownlint docs/**/*.md

Visual Documentation Systems

Storybook configuration example:

// .storybook/main.js
module.exports = {
  stories: ['../src/**/*.stories.mdx'],
  addons: [
    '@storybook/addon-docs',
    '@storybook/addon-controls'
  ]
};

Component story files should include interactive examples:

// Button.stories.jsx
export const Primary = () => (
  <Button 
    backgroundColor="#ff0"
    label="Button"
    onClick={() => console.log('clicked')}
  />
);

Documentation Accessibility Requirements

Images Must Include Alt Text

<!-- Correct example -->
![Component structure diagram](./structure.png "Component hierarchy")

<!-- Incorrect example -->
![](./structure.png)

Code Block Language Annotation

```javascript
// Correct: Language specified
function test() {}
```

```plaintext
// Incorrect: No language specified
function test() {}
```

Documentation Version Management

Adopt semantic version control:

docs-v1.2.3/
├── latest/        # Current stable version
├── v1.2.2/       # Historical version
└── v1.1.0/

Documentation Review Mechanism

Establish a documentation CR checklist:

1. All interface changes must synchronously update API documentation
2. New configuration items must be documented in CHANGELOG
3. Breaking changes must be labeled BREAKING CHANGE
4. Example code must pass ESLint checks

Internationalized Documentation Handling

Recommended multilingual documentation structure:

docs/
├── zh-CN/
│   ├── getting-started.md
│   └── api-reference.md
└── en-US/
    ├── getting-started.md
    └── api-reference.md

Use tools like crowdin to manage translation workflows:

# crowdin.yml
files:
  - source: '/docs/en-US/**/*.md'
    translation: '/docs/%locale%/%original_file_name%'

Documentation Performance Optimization

Image Compression Standards

# Process images using sharp
npx sharp input.png -resize 800 -quality 80 output.webp

Chunk Loading Strategy

Split large documents into multiple sections:

[Quick Start](./getting-started.md)
[Advanced Configuration](./advanced.md)
[API Reference](./api.md)

Documentation Feedback Mechanism

Add feedback entries at the bottom of each document:

<div class="doc-feedback">
  <p>Was this document helpful?</p>
  <button data-response="yes">Yes</button>
  <button data-response="no">No</button>
</div>

Accompanying feedback collection script:

document.querySelectorAll('[data-response]').forEach(btn => {
  btn.addEventListener('click', () => {
    fetch('/api/feedback', {
      method: 'POST',
      body: JSON.stringify({
        page: location.pathname,
        response: btn.dataset.response
      })
    });
  });
});