Documentation Standards

Purpose

Maintaining high-quality documentation ensures that code is understandable, maintainable, and usable by other developers and stakeholders.

Types of Documentation

Code Documentation

• Use typing to document the types of the variables, functions, and methods.
• Use docstrings to document the purpose of the code.
• Code should be self-explanatory. Code comments are usually a smell of low readability code.
• If code is complex by necessity, use comments to explain the code.

Repo Documentation

• README files with project overview, setup instructions, and usage examples.

Project Documentation

• Detailed tutorials, guides, and references go into our engineering docs.

Best Practices

• Write clear, concise, and easy-to-understand documentation.
• Avoid jargon and overly technical language.
• Every PR should contain a link to the documentation that was changed.