Back to English for Coders
AdvancedAdults
Writing Technical Documentation
Good code needs good documentation. Technical writing is a skill that makes your projects usable and maintainable by others (and your future self!).
Key principles:
1. **Be Clear and Concise:** Avoid jargon where possible. Get straight to the point.
2. **Know Your Audience:** Are you writing for beginners or experts? Tailor your language accordingly.
3. **Provide Examples:** Code snippets are worth a thousand words. Show how to use the function or component.
4. **Structure Your Document:** Use headings, lists, and bold text to make the document easy to scan. A good structure includes a purpose, parameters/arguments, return values, and examples.
Example of documenting a function:
This is clear, simple, and tells another developer everything they need to know.
Key principles:
1. **Be Clear and Concise:** Avoid jargon where possible. Get straight to the point.
2. **Know Your Audience:** Are you writing for beginners or experts? Tailor your language accordingly.
3. **Provide Examples:** Code snippets are worth a thousand words. Show how to use the function or component.
4. **Structure Your Document:** Use headings, lists, and bold text to make the document easy to scan. A good structure includes a purpose, parameters/arguments, return values, and examples.
Example of documenting a function:
/**
* Calculates the sum of two numbers.
* @param {number} a - The first number.
* @param {number} b - The second number.
* @returns {number} The sum of a and b.
*/
function add(a, b) {
return a + b;
}This is clear, simple, and tells another developer everything they need to know.