Skip to main content

Technical Writing Style Guide

· 3 min read
Yang Chu
Yang Chu
Product Manager @ Cyritex
Yakun Wu
Yakun Wu
VP @ Cyritex

This document aims to standardize technical documentation writing style to ensure consistency and readability.

Spacing Guidelines

Spacing Between Languages

  • Add spaces between Chinese and English words

    • ✅ Correct: 我们使用 Docker 来部署应用
    • ❌ Incorrect: 我们使用Docker来部署应用

  • Add spaces between Chinese characters and numbers

    • ✅ Correct: 系统需要 2 GB 内存
    • ❌ Incorrect: 系统需要2GB内存

Special Cases

  • Add spaces between links and Chinese text

Punctuation Guidelines

Chinese Punctuation

  • Use full-width punctuation in Chinese sentences

    • ✅ Correct: 请按照以下步骤操作：
    • ❌ Incorrect: 请按照以下步骤操作:

  • Use full-width commas and periods in Chinese sentences

    • ✅ Correct: 安装完成后，请重启系统。
    • ❌ Incorrect: 安装完成后,请重启系统.

English Punctuation

  • Use half-width punctuation in English sentences
    • ✅ Correct: The installation is complete. Please restart.
    • ❌ Incorrect: The installation is complete。Please restart。
  • Use half-width punctuation in code and command line examples
  • Leave one blank line before and after code blocks
  • Wrap inline code with backticks (`)

Formatting Guidelines

Heading Format

  • Don't skip heading levels (e.g., from h1 directly to h3)
  • Keep headings concise
  • Use heading levels from h1 to h6 in descending order

List Format

  • Use - or * for unordered lists
  • Use 1. 2. etc. for ordered lists
  • Maintain consistent list alignment
  • Avoid deep nesting (recommend no more than three levels)

Proper Noun Guidelines

  • Maintain consistent capitalization for product names and technical terms

    • ✅ Correct: JavaScript, Docker, Kubernetes
    • ❌ Incorrect: javascript, docker, kubernetes

  • Provide explanations for technical terms on first appearance

  • Use consistent terminology throughout the documentation

Additional Recommendations

Document Structure

  • Provide a brief introduction at the beginning
  • Use diagrams and charts where appropriate
  • Highlight important information using callouts
  • Include table of contents for longer documents

Writing Style

  • Use clear and concise language
  • Avoid colloquial expressions
  • Maintain an objective, professional tone
  • Use active voice, avoid passive voice

Documentation Maintenance

  • Regularly check document relevance
  • Update outdated content promptly
  • Keep version information current
  • Verify accuracy of cross-references

Example Demonstration

Here's an example of a properly formatted document:

# Product Introduction

This document introduces the basic concepts and usage of Docker containers.

## What is Docker?

Docker is an open-source application container engine that allows developers to package their applications and dependencies into a portable container.

## Key Features

- Lightweight container virtualization
- Cross-platform support
- Version control and component reuse