Awesome Reviewers

Documentation should follow established best practices to ensure clarity, consistency, and usefulness:

1. Use proper link types: Use relative links for internal resources and absolute HTTP links only for external resources. ```python

   Good

   • Task SDK Overview <../concepts/taskflow.html>_

   Bad

   • Task SDK Overview <https://airflow.apache.org/docs/apache-airflow/stable/concepts/taskflow.html>_ ```

2. Write in complete sentences: Ensure all descriptions, especially in API documentation and migration notes, are complete sentences with proper grammar and punctuation.

3. Document API components thoroughly: Include docstrings for all API functions, methods, and classes with detailed information about parameters, return values, and usage examples.

   @task
   def process_data(data_path: str, limit: Optional[int] = None) -> Dict[str, Any]:
       """
       Process data from the specified path with optional limit.
          
       :param data_path: Path to the data file to process
       :param limit: Maximum number of records to process, None for unlimited
       :return: Dictionary containing processed results
       """
       # Implementation
   

4. Document all API variants: Ensure “sub” decorators and related API components (like @task.skip_if) are documented alongside their parent components.

5. Use enhanced documentation directives: Use specialized directives like exampleinclude instead of literalinclude to provide “[sources]” links that give users access to complete context and code examples.

Following these practices improves documentation usability, making it easier for developers to understand and correctly implement the documented functionality.

This site is open source. Improve this page.