How to Write Effective Technical Documentation: Carriers, Required Docs, Best Practices, Maintenance, and Recommended Reading

Programmers often dislike two types of people: those who don't write documentation and those who force them to write it. However, a well‑structured, context‑rich document can pre‑empt many issues.

Writing technical documentation is a developer's duty, as important as writing readable code. This article systematically teaches how to write and improve documentation.

1. What medium to use

Persistent documents: use a searchable knowledge‑base tool such as an internal wiki or organizational knowledge base. Private documents or Word files are not recommended for large‑scale sharing.

Short‑term collaborative documents: prefer online multi‑user tools like Tencent Docs.

Overall recommendation: use Tencent Docs for review/co‑creation, then move the final version to a knowledge‑base for long‑term storage.

2. Which documents should be written

Documentation is a tool for efficient communication, collaboration, knowledge accumulation and sharing. Write docs when they provide value to multiple readers. Typical documents include:

Overall architecture design docs (e.g., “Search Engine Architecture Design”, “Search Core Design”, “Online Search System Design”, “Content Architecture Refactoring”).

Key feature design docs (e.g., “Search Scoring Design”, “Search Performance Evaluation Framework”).

General experience summaries (e.g., “Timestamp to String Conversion Causing Service Hang”, “Pipeline Build Manual”, “GCC‑8 Optimization Bug Causing Memory Leak”).

Project experience summaries (e.g., “Search Engine Upgrade Project Summary”, “Search Core Indexing Performance Optimization”, “Content Architecture Refactoring Project Summary”).

Framework docs for other developers (e.g., “C++ Scoring Plugin Development Guide”, “Content Ingestion Operator Manual”).

User‑facing feature introductions (e.g., “Quick Start – Search Engine Integration Guide”, “Force Recall Intervention Usage”).

Complex case investigation summaries (e.g., “Document Ingestion Latency Investigation”, “Unrecall Document Investigation”).

Research summaries (e.g., “ES Retrieval Matching Word Research”, “Lua Plugin Performance Research”).

New‑comer onboarding docs (e.g., “Search Engine Newcomer Pack”, “First Day to First Requirement”, “Search Middleware Development Handbook”).

In short, write a document only when it brings value to multiple readers.

3. How to write good documentation

3.1 Document templates

Our team provides several standard templates:

Backend Lecture Document Template

Backend Performance Evaluation Document Template

Backend Architecture Review Document Template

Technical Product Case Investigation Summary Template

Case Study Template

3.2 Formatting rules

Directory must exist for documents longer than one screen and use numeric ordering.

Owner and editors must be listed at the beginning of the article.

Follow Chinese copywriting guidelines for spacing between Chinese/English, numbers/units, punctuation, etc.

3.3 Content organization

Core principles: accurate, complete, clear, focused; aim to let readers obtain expected information efficiently.

Presentation tools: use GIFs for complex steps (e.g., ScreenToGif).

Appropriate granularity: avoid too coarse or too fine detail; adjust based on target audience.

3.4 Technical review document suggestions

Typical structure follows the pyramid principle: background, overall architecture, detailed design, trade‑offs, schedule, and any additional materials.

4. Document maintenance

4.1 Owner system

Each document has an owner responsible for upkeep; others may update errors, but the owner performs final review. Series documents are overseen by a domain leader.

4.2 Routine vs. on‑demand updates

Treat updates like code maintenance. Critical docs (e.g., external API specs) need timely updates with each release. Low‑traffic docs (e.g., newcomer handbooks) can be updated when needed.

5. Recommended reading

“The Pyramid Principle”

“A Small Red Writing Book”

Feel free to share your own documentation challenges in the comments; the best comment will win a custom Tencent Cloud developer eye mask.