Ensiklopedia VibeKoding: An Introduction to Technical Writing.Ensiklopedia VibeKoding: An Introduction to Technical Writing.
Does anyone read the documentation you write? Many developers think "if the code works, that's enough — documentation can wait." The result: new hires can't understand the project, API integration relies entirely on verbal communication, and six months later even you've forgotten why you designed it that way. This chapter helps you master the core methods of technical writing so your documentation is actually read, understood, and useful.Does anyone read the documentation you write? Many developers think "if the code works, that's enough — documentation can wait." The result: new hires can't understand the project, API integration relies entirely on verbal communication, and six months later even you've forgotten why you designed it that way. This chapter helps you master the core methods of technical writing so your documentation is actually read, understood, and useful.
What will you learn in this article?What will you learn in this article?
| Chapter | Content | Core Concepts |
|---|---|---|
| Chapter 1 | Document types and structure | How to write different documents |
| Chapter 2 | Writing principles | Clear, accurate, concise |
| Chapter 3 | Practical comparisons | Good docs vs. bad docs |
| Chapter 4 | Document maintenance | Keeping documentation up to date |
After reading this chapter, you will be able to write technical documentation that is well-structured, accurate, and easy to maintain.After reading this chapter, you will be able to write technical documentation that is well-structured, accurate, and easy to maintain.
------
Code tells the computer "how"; documentation tells people "why." A project without documentation is like an appliance without a manual — it works, but using it is pure guesswork.Code tells the computer "how"; documentation tells people "why." A project without documentation is like an appliance without a manual — it works, but using it is pure guesswork.
- Reduced Communication Costs: New team members can onboard independently, reducing repeated explanations - Preserved Decision Context: Recording "why," not just "what" - Increased Project Credibility: Good documentation is the face of an open source project - Accelerated Collaboration: API documentation enables parallel front-end and back-end development- Reduced Communication Costs: New team members can onboard independently, reducing repeated explanations - Preserved Decision Context: Recording "why," not just "what" - Increased Project Credibility: Good documentation is the face of an open source project - Accelerated Collaboration: API documentation enables parallel front-end and back-end development
------
Use the interactive component below to learn the standard structure for different types of documents:Use the interactive component below to learn the standard structure for different types of documents:
| Document Type | Target Audience | Core Content |
|---|---|---|
| README | Everyone | What the project is, how to use it, how to contribute |
| API Documentation | API consumers | Endpoints, parameters, responses, error codes |
| Architecture Docs | Development team | System design, technology choices, data flow |
| Changelog | Users/developers | Version changes, additions/fixes/breaking changes |
| Contributing Guide | Contributors | Dev environment, code standards, PR process |
A good README should include:A good README should include:
------
markdown <!-- Bad: vague and unclear --> This function processes data. <!-- Good: specific and clear --> Converts raw order data to invoice format, including tax calculation and currency conversion.
Before writing documentation, ask: Who will read this? What information do they need?Before writing documentation, ask: Who will read this? What information do they need?
markdown <!-- Bad: text description only --> Call the createUser function, passing in the username and email parameters. <!-- Good: runnable example --> const user = await createUser({ name: 'Zhang San', email: 'zhangsan@example.com' }) // Returns: { id: 'u_123', name: 'Zhang San', createdAt: '2025-01-15' }
------
Use the interactive component below to compare good and bad technical writing:Use the interactive component below to compare good and bad technical writing:
CODE # Bad fix bug update code # Good (Conventional Commits) fix: resolve login page white screen issue on Safari feat: support batch export of PDF reports docs: update example code in API authentication section
javascript // Bad: describes "what" (the code already says this) // Iterate through the array for (const item of items) { ... } // Good: explains "why" // Iterate in reverse because forward iteration skips the next item when deleting for (let i = items.length - 1; i >= 0; i--) { ... }
------
Keep documentation and code in the same repository, managed with the same workflow:Keep documentation and code in the same repository, managed with the same workflow:
| Problem | Solution |
|---|---|
| Outdated documentation | Force documentation updates with code changes (PR checks) |
| No one maintains it | Assign documentation owners |
| Content duplication | Single source of truth, link to it elsewhere |
------
LLMs are almost "naturally gifted" in technical writing — generating documentation, improving expression, and translating content are all strong suits.LLMs are almost "naturally gifted" in technical writing — generating documentation, improving expression, and translating content are all strong suits.
> Prompt:> Prompt:
> ```> ```
> Based on the following Express route code, generate complete API documentation including:> Based on the following Express route code, generate complete API documentation including:
> - Endpoint path and method> - Endpoint path and method
> - Request parameters (path params, query params, request body) and types> - Request parameters (path params, query params, request body) and types
> - Success and error response examples> - Success and error response examples
> - curl usage examples> - curl usage examples
>>
> [Paste your route code]> [Paste your route code]
> ```> ```
> Prompt:> Prompt:
> ```> ```
> Please improve the expression of the following technical documentation:> Please improve the expression of the following technical documentation:
> 1. Use concise and clear language, remove redundant expressions> 1. Use concise and clear language, remove redundant expressions
> 2. Replace passive voice with active voice> 2. Replace passive voice with active voice
> 3. Keep technical terms accurate> 3. Keep technical terms accurate
> 4. Add necessary code examples> 4. Add necessary code examples
> Preserve the original meaning; only improve the quality of expression.> Preserve the original meaning; only improve the quality of expression.
>>
> [Paste your documentation content]> [Paste your documentation content]
> ```> ```
> Prompt:> Prompt:
> ```> ```
> Based on the following project information, generate a high-quality README.md:> Based on the following project information, generate a high-quality README.md:
> - Project name: [name]> - Project name: [name]
> - One-line description: [description]> - One-line description: [description]
> - Tech stack: [list]> - Tech stack: [list]
> - Core features: [list]> - Core features: [list]
>>
> Must include: project introduction, quick start, features,> Must include: project introduction, quick start, features,
> installation steps (with code), usage examples, contributing guide, license.> installation steps (with code), usage examples, contributing guide, license.
> ```> ```
Always verify technical details in AI-generated documentation — it may fabricate non-existent API parameters or incorrect return values. Always cross-check against the actual code.Always verify technical details in AI-generated documentation — it may fabricate non-existent API parameters or incorrect return values. Always cross-check against the actual code.
------
Writing documentation is not wasting time — it's saving future time. The 30 minutes you spend writing documentation today could save 10 people an hour each. Good documentation is the best investment you can make for your team.Writing documentation is not wasting time — it's saving future time. The 30 minutes you spend writing documentation today could save 10 people an hour each. Good documentation is the best investment you can make for your team.
------