When writing or improving documentation for agency swarm, your primary goal is to make sure the user sees only the information he wants to see. No more, no less.
- Write documentation in an easy to understand conversational language.
- Use simple language and clear terms.
- Docs should be easily readable by an 8th grader.
- Be brief and to the point.
- Make documentation actionable. Place code snippets at the top so users can easily copy and paste them. Provide only essential context above the code. Move any complex or detailed explanations to the end of the page.
- The more important the information is, the higher it should be on the page.
- Highlight the important parts by using bold, components, etc.
- Hide complexity under tabs, dropdowns, etc.
- Split pages into sub pages if needed. Each page must be shorter than 150 lines.
You can utilize various components from mintlify:
Collapsible sections for optional or detailed content:
<Accordion title="Advanced Options" defaultOpen={false}>
Content here
</Accordion>
Switch between different code examples or content:
<Tabs>
<Tab title="Python">Python code</Tab>
<Tab title="JavaScript">JS code</Tab>
</Tabs>
Highlight key links or concepts:
<Card title="Getting Started" icon="rocket-launch" href="/quickstart">
Start building your first agency
</Card>
Display sequential instructions:
<Steps>
<Step title="Install">Install the package</Step>
<Step title="Configure">Set up your config</Step>
</Steps>
Group related code examples:
<CodeGroup>
```python example.py
# Python version
// JS version
```
For API documentation:
<ParamField param="name" type="string" required>
Parameter description
</ParamField>
<ResponseField name="status" type="string">
Response field description
</ResponseField>
Before starting any task, you MUST read the following examples of good written docs files:
Adhere closely to the writing style and structure in these examples.
- Analyze the feedback provided by the user and deteremine which specific sections you need to update.
- If there is a lot of feedback, create a to-do list for yourself and break it down.
- Only update the required parts, do not add anything unrequested. Perform minimal changes, keep everything unaffected by feedback as is. Only update the parts and the pages that are explicitly requested.
- If asked to move the page, keep consistent folder and file structure, matching the structure in the
./docs/docs.json
file.
- Ask the user to review the changes and provide feedback.
- Analyze the information or the relevant code provided by the user.
- If user has not provided enough information, as the user a set of 3-5 relevant questions about the feature.
- For example:
- What is the use case for this?
- Where can I see relevant files?
- Do you have any example code snippets?
- Why did you create this feature in the first place?
- What does the user have to know before they can start using it?
- etc...
- Create a new page reference in the
./docs/docs.json
file in the appropriate group and sub group.
- If it's unclear where to place the page, ask the user for clarification.
- Make sure the folder strcuture in docs folder matches the structure in the
./docs/docs.json
file.
- Write the page content using the same path, following all the rules above.
- Ask the user to review the page and provide feedback.
- Implement any adjustments as needed. See "Updating Existing Pages" section below.
- Mintlify Documentation - Check if you need clarification about how mintlify works or looking for any other components.