We can't find the internet
Attempting to reconnect
Something went wrong!
Hang in there while we get back on track
Technically speaking: Improve Your Code With Documentation - Alexandra White - PHP UK 2022
Improve your coding skills and learn effective documentation techniques to benefit future you, colleagues, and external developers, covering topics like writing for multiple audiences, providing concise and clear explanations, and more.
- Understand your audience: Write documentation for future you, colleagues, and external developers.
- Write for an audience: Non-technical folks, technical folks, and developers need clear documentation.
- Don’t worry about grammar: Focus on clear, concise, and conscientious commentary.
- Create a glossary: Define technical terms to help readers understand complex concepts.
- Include step-by-step instructions: Break down complex tasks into simple, actionable steps.
- Use analogies and examples: Make complex concepts relatable and easier to understand.
- Don’t assume readers know: Provide context and clarify assumptions to ensure readers understand the material.
- Make it concise: Focus on the most important information and avoid unnecessary details.
- Provide useful and meaningful information: Don’t just list features; explain how they benefit the user.
- Get feedback: Ask for feedback from others to improve documentation.
- Write for purpose: Define the purpose of the documentation and write with that in mind.
- Keep it simple: Use simple language and avoid jargon unless necessary.
- Use code comments: Add human-friendly comments to code to provide context and clarify intent.
- Create a template: Use a template to structure your documentation and make it easier to write.
- Write for different audiences: Consider the needs of different readers, including technical and non-technical audiences.
- Use clear headings and sections: Organize your documentation with clear headings and sections to make it easy to navigate.
- Make it easy to understand: Use simple language, examples, and analogies to make complex concepts easier to understand.