# AI Style Guide

This style guide is intended to ensure clear, consistent, and maintainable documentation for ControlFlow. It is primarily aimed at LLM agents that assist with writing documentation, but it may also be useful for other contributors.

## General Guidelines
- If you are given instructions that you feel are appropriate to memorialize in this style guide, indicate to the user that they should be added.
- Use consistent terminology throughout the documentation. Always refer to the library as "ControlFlow".
- Link to related concepts, patterns, or API references when appropriate to help users navigate the documentation.
- Do not end documention with "Conclusions", "Best Practices", or other lists. Documentation is not a blog post.

## Tone and Style
- Maintain a professional but approachable tone.
- Write concisely and directly, avoiding unnecessary jargon.

## Code
- Use `import controlflow as cf` instead of importing top-level classes and functions directly
- Code examples should be complete, including all necessary imports, so that users can copy and paste them directly. The only exception is a tutorial that is building up an example step by step.
- Code examples should wrap at ~80 characters to ensure readability on all devices.
- For illustrative examples, provide simple, focused examples that demonstrate a specific concept or pattern.
- For "full" examples, provide realistic, practical examples that demonstrate actual use cases of ControlFlow.

### Tasks
- Make sure that the example code in the documentation reflects the best practices for task definition, including suitable result types and instructions.
- Each task should come with unambiguous instructions, particularly when the task name doesn't clearly indicate the expected outcome. 
- If placeholder tasks are required in examples, consider using a string result type with a comment to denote it's a placeholder, for instance, `result_type=str # Placeholder for actual result`
- The default `result_type` is `str`, so there's no need to provide it explicitly if you want a string result.

## Mintlify
- Mintlify components expect newlines before and after tags e.g. <Tip>\nThis is a tip\n</Tip>
- Mintlify displays the page's title as an H1 element, so there is no need to add an initial top-level header to any doc. Instead, the title should be added to the doc's frontmatter e.g. `---\ntitle: My Title\n---`. 
- Because the title is displayed as an H1, all subsequent headers should be H2 or lower.




