ai-mirow-projects
/
swarms
mirror of https://github.com/kyegomez/swarms
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs formatting contributing to docs

Browse Source
master
Kye Gomez 3 days ago
parent 026ed288e2
commit e62f2e9947
1 changed files with 54 additions and 1 deletions
Show Stats Download Patch File Download Diff File

55
docs/contributors/docs.md
Unescape View File

@ -4,7 +4,7 @@
The Swarms documentation serves as the primary gateway for developer and user engagement within the Swarms ecosystem. Comprehensive, clear, and consistently updated documentation accelerates adoption, reduces support requests, and helps maintain a thriving developer community. This guide offers an in-depth, actionable framework for contributing to the Swarms documentation site, covering the full lifecycle from initial setup to the implementation of our bounty-based rewards program. The Swarms documentation serves as the primary gateway for developer and user engagement within the Swarms ecosystem. Comprehensive, clear, and consistently updated documentation accelerates adoption, reduces support requests, and helps maintain a thriving developer community. This guide offers an in-depth, actionable framework for contributing to the Swarms documentation site, covering the full lifecycle from initial setup to the implementation of our bounty-based rewards program.
This enterprise-focused guide is designed for first-time contributors, experienced engineers, and technical writers alike. It emphasizes professional standards, collaborative development practices, and incentivized participation through our structured rewards program. Contributors play a key role in helping us scale and evolve our ecosystem by improving the clarity, accessibility, and technical depth of our documentation. This guide is designed for first-time contributors, experienced engineers, and technical writers alike. It emphasizes professional standards, collaborative development practices, and incentivized participation through our structured rewards program. Contributors play a key role in helping us scale and evolve our ecosystem by improving the clarity, accessibility, and technical depth of our documentation.
--- ---
@ -14,9 +14,13 @@ Documentation in the Swarms ecosystem is not simply static text. It is a living,
**Objectives of this Guide:** **Objectives of this Guide:**
- Define a standardized contribution workflow for Swarms documentation. - Define a standardized contribution workflow for Swarms documentation.
- Clarify documentation roles, responsibilities, and submission expectations. - Clarify documentation roles, responsibilities, and submission expectations.
- Establish quality benchmarks, review procedures, and formatting rules. - Establish quality benchmarks, review procedures, and formatting rules.
- Introduce the Swarms Documentation Bounty Program to incentivize excellence. - Introduce the Swarms Documentation Bounty Program to incentivize excellence.
--- ---
@ -36,10 +40,15 @@ By treating documentation as a core product component, we ensure continuity, sca
The Swarms ecosystem consists of multiple tightly integrated components that serve developers and enterprise clients alike: The Swarms ecosystem consists of multiple tightly integrated components that serve developers and enterprise clients alike:
- **Core Documentation Repository**: The main documentation hub for all Swarms technologies [GitHub](https://github.com/kyegomez/swarms). - **Core Documentation Repository**: The main documentation hub for all Swarms technologies [GitHub](https://github.com/kyegomez/swarms).
- **Rust SDK (`swarms_rs`)**: Official documentation for the Rust implementation. [Repo](https://github.com/The-Swarm-Corporation/swarms-rs). - **Rust SDK (`swarms_rs`)**: Official documentation for the Rust implementation. [Repo](https://github.com/The-Swarm-Corporation/swarms-rs).
- **Tools Documentation (`swarms_tools`)**: Guides for CLI and GUI utilities. - **Tools Documentation (`swarms_tools`)**: Guides for CLI and GUI utilities.
- **Hosted API Reference**: Up-to-date REST API documentation: [Swarms API Docs](https://docs.swarms.world/en/latest/swarms_cloud/swarms_api/). - **Hosted API Reference**: Up-to-date REST API documentation: [Swarms API Docs](https://docs.swarms.world/en/latest/swarms_cloud/swarms_api/).
- **Marketplace & Chat**: Web platforms and communication interfaces [swarms.world](https://swarms.world). - **Marketplace & Chat**: Web platforms and communication interfaces [swarms.world](https://swarms.world).
All contributions funnel through the `docs/` directory in the core repo and are structured via MkDocs. All contributions funnel through the `docs/` directory in the core repo and are structured via MkDocs.
@ -51,13 +60,17 @@ All contributions funnel through the `docs/` directory in the core repo and are
Swarms documentation is powered by [MkDocs](https://www.mkdocs.org/), an extensible static site generator tailored for project documentation. To contribute, you should be comfortable with: Swarms documentation is powered by [MkDocs](https://www.mkdocs.org/), an extensible static site generator tailored for project documentation. To contribute, you should be comfortable with:
- **Markdown**: For formatting structure, code snippets, lists, and links. - **Markdown**: For formatting structure, code snippets, lists, and links.
- **MkDocs Configuration**: `mkdocs.yml` manages structure, theme, and navigation. - **MkDocs Configuration**: `mkdocs.yml` manages structure, theme, and navigation.
- **Version Control**: GitHub for branching, version tracking, and collaboration. - **Version Control**: GitHub for branching, version tracking, and collaboration.
**Recommended Tooling:** **Recommended Tooling:**
- Markdown linters to enforce syntax consistency. - Markdown linters to enforce syntax consistency.
- Spellcheckers to ensure grammatical accuracy. - Spellcheckers to ensure grammatical accuracy.
- Doc generators for automated API reference extraction. - Doc generators for automated API reference extraction.
--- ---
@ -66,14 +79,19 @@ Swarms documentation is powered by [MkDocs](https://www.mkdocs.org/), an extensi
### 5.1 System Requirements ### 5.1 System Requirements
- **Git** v2.30 or higher - **Git** v2.30 or higher
- **Node.js** and **npm** for related dependency management - **Node.js** and **npm** for related dependency management
- **MkDocs** and **Material for MkDocs** theme (`pip install mkdocs mkdocs-material`) - **MkDocs** and **Material for MkDocs** theme (`pip install mkdocs mkdocs-material`)
- A GitHub account with permissions to fork and submit pull requests - A GitHub account with permissions to fork and submit pull requests
### 5.2 Forking the Swarms Repository ### 5.2 Forking the Swarms Repository
1. Visit: `https://github.com/kyegomez/swarms` 1. Visit: `https://github.com/kyegomez/swarms`
2. Click on **Fork** to create your version of the repository 2. Click on **Fork** to create your version of the repository
### 5.3 Clone and Configure Locally ### 5.3 Clone and Configure Locally
@ -105,8 +123,10 @@ docs/
### 6.1 SDK/Tools Directories ### 6.1 SDK/Tools Directories
- **Rust SDK (`docs/swarms_rs`)**: Guides, references, and API walkthroughs for the Rust-based implementation. - **Rust SDK (`docs/swarms_rs`)**: Guides, references, and API walkthroughs for the Rust-based implementation.
- **Swarms Tools (`docs/swarms_tools`)**: CLI guides, GUI usage instructions, and architecture documentation. - **Swarms Tools (`docs/swarms_tools`)**: CLI guides, GUI usage instructions, and architecture documentation.
Add new `.md` files in the folder corresponding to your documentation type. Add new `.md` files in the folder corresponding to your documentation type.
### 6.2 Configuring Navigation in MkDocs ### 6.2 Configuring Navigation in MkDocs
@ -130,22 +150,31 @@ nav:
### 7.1 Content Standards ### 7.1 Content Standards
- **Clarity**: Explain complex ideas in simple, direct language. - **Clarity**: Explain complex ideas in simple, direct language.
- **Style Consistency**: Match the tone and structure of existing docs. - **Style Consistency**: Match the tone and structure of existing docs.
- **Accuracy**: Validate all technical content and code snippets. - **Accuracy**: Validate all technical content and code snippets.
- **Accessibility**: Include alt text for images and use semantic Markdown. - **Accessibility**: Include alt text for images and use semantic Markdown.
### 7.2 Markdown Best Practices ### 7.2 Markdown Best Practices
- Sequential heading levels (`#`, `##`, `###`) - Sequential heading levels (`#`, `##`, `###`)
- Use fenced code blocks with language identifiers - Use fenced code blocks with language identifiers
- Create readable line spacing and avoid unnecessary line breaks - Create readable line spacing and avoid unnecessary line breaks
### 7.3 File Placement Protocol ### 7.3 File Placement Protocol
Place `.md` files into the correct subdirectory: Place `.md` files into the correct subdirectory:
- **Rust SDK Docs**: `docs/swarms_rs/` - **Rust SDK Docs**: `docs/swarms_rs/`
- **Tooling Docs**: `docs/swarms_tools/` - **Tooling Docs**: `docs/swarms_tools/`
--- ---
@ -172,6 +201,7 @@ mkdocs serve
- Use prefix and description, e.g.: - Use prefix and description, e.g.:
- `feature/docs-api-pagination` - `feature/docs-api-pagination`
- `fix/docs-typo-tooling` - `fix/docs-typo-tooling`
### 9.2 Writing Clear Commits ### 9.2 Writing Clear Commits
@ -200,7 +230,9 @@ docs(swarms_tools): correct CLI usage example
Every PR undergoes automated and human review: Every PR undergoes automated and human review:
- **CI Checks**: Syntax validation, link checking, and formatting - **CI Checks**: Syntax validation, link checking, and formatting
- **Manual Review**: Maintain clarity, completeness, and relevance - **Manual Review**: Maintain clarity, completeness, and relevance
- **Iteration**: Collaborate through feedback and finalize changes - **Iteration**: Collaborate through feedback and finalize changes
Once approved, maintainers will merge and deploy the updated documentation. Once approved, maintainers will merge and deploy the updated documentation.
@ -213,9 +245,13 @@ To foster continuous improvement, we offer structured rewards for eligible contr
### 11.1 Contribution Types ### 11.1 Contribution Types
- Creating comprehensive new tutorials and deep dives - Creating comprehensive new tutorials and deep dives
- Updating outdated references and examples - Updating outdated references and examples
- Fixing typos, grammar, and formatting errors - Fixing typos, grammar, and formatting errors
- Translating existing content - Translating existing content
### 11.2 Reward Structure ### 11.2 Reward Structure
@ -239,18 +275,26 @@ To foster continuous improvement, we offer structured rewards for eligible contr
## 12. Best Practices for Efficient Contribution ## 12. Best Practices for Efficient Contribution
- **Stay Updated**: Sync your fork weekly to avoid merge conflicts - **Stay Updated**: Sync your fork weekly to avoid merge conflicts
- **Atomic PRs**: Submit narrowly scoped changes for faster review - **Atomic PRs**: Submit narrowly scoped changes for faster review
- **Use Visuals**: Support documentation with screenshots or diagrams - **Use Visuals**: Support documentation with screenshots or diagrams
- **Cross-Reference**: Link to related documentation for completeness - **Cross-Reference**: Link to related documentation for completeness
- **Version Awareness**: Specify SDK/tool versions in code examples - **Version Awareness**: Specify SDK/tool versions in code examples
--- ---
## 13. Style Guide Snapshot ## 13. Style Guide Snapshot
- **Voice**: Informative, concise, and respectful - **Voice**: Informative, concise, and respectful
- **Terminology**: Use standardized terms (`Swarm`, `Swarms`) consistently - **Terminology**: Use standardized terms (`Swarm`, `Swarms`) consistently
- **Code**: Format snippets using language-specific linters - **Code**: Format snippets using language-specific linters
- **Accessibility**: Include alt attributes and avoid ambiguous links - **Accessibility**: Include alt attributes and avoid ambiguous links
--- ---
@ -260,7 +304,9 @@ To foster continuous improvement, we offer structured rewards for eligible contr
We use analytics and community input to prioritize improvements: We use analytics and community input to prioritize improvements:
- **Traffic Reports**: Track most/least visited pages - **Traffic Reports**: Track most/least visited pages
- **Search Logs**: Detect content gaps from common search terms - **Search Logs**: Detect content gaps from common search terms
- **Feedback Forms**: Collect real-world user input - **Feedback Forms**: Collect real-world user input
Schedule quarterly audits to refine structure and content across all repositories. Schedule quarterly audits to refine structure and content across all repositories.
@ -271,9 +317,13 @@ Schedule quarterly audits to refine structure and content across all repositorie
Promote your contributions via: Promote your contributions via:
- **Swarms Discord**: https://discord.gg/jM3Z6M9uMq - **Swarms Discord**: https://discord.gg/jM3Z6M9uMq
- **Swarms Telegram**: https://t.me/swarmsgroupchat - **Swarms Telegram**: https://t.me/swarmsgroupchat
- **Swarms Twitter**: https://x.com/swarms_corp - **Swarms Twitter**: https://x.com/swarms_corp
- **Startup Program Showcases**: https://www.swarms.xyz/programs/startups - **Startup Program Showcases**: https://www.swarms.xyz/programs/startups
Active contributors are often spotlighted for leadership roles and community awards. Active contributors are often spotlighted for leadership roles and community awards.
@ -283,8 +333,11 @@ Active contributors are often spotlighted for leadership roles and community awa
## 16. Resource Index ## 16. Resource Index
- Core GitHub Repo: https://github.com/kyegomez/swarms - Core GitHub Repo: https://github.com/kyegomez/swarms
- Rust SDK Repo: https://github.com/The-Swarm-Corporation/swarms-rs - Rust SDK Repo: https://github.com/The-Swarm-Corporation/swarms-rs
- Swarms API Docs: https://docs.swarms.world/en/latest/swarms_cloud/swarms_api/ - Swarms API Docs: https://docs.swarms.world/en/latest/swarms_cloud/swarms_api/
- Marketplace: https://swarms.world - Marketplace: https://swarms.world
Join our monthly Documentation Office Hours for real-time mentorship and Q&A. Join our monthly Documentation Office Hours for real-time mentorship and Q&A.

Write Preview
Loading…
Cancel
Save