Contributing to the Knowledge Base¶

Thank you for your interest in contributing to the AI-Assisted Development Knowledge Base! This guide will help you understand how to contribute effectively to both learning content and production templates.

🤝 How to Contribute¶

Types of Contributions¶

We welcome contributions in several areas:

📚 Learning Content¶

New Techniques: Advanced prompting or context engineering methods
Case Studies: Real-world implementation experiences and success stories
Tutorials: Step-by-step guides for specific scenarios
Best Practices: Proven patterns and anti-patterns documentation
Translations: Content in additional languages

🏗️ Production Templates¶

CDF Templates: New deployment or configuration templates
Quality Improvements: Enhanced error handling and validation
Integration Examples: Examples for new CDF features or services
Testing Frameworks: Improved validation and testing approaches

🛠️ Documentation & Tools¶

Documentation: Improvements to existing guides and tutorials
Tools: Scripts, utilities, and automation for the knowledge base
Examples: Code examples and sample implementations
Templates: Documentation templates and standards

🚀 Getting Started¶

Prerequisites¶

Git installed on your system
A GitHub account
Basic understanding of Markdown
For CDF templates: Python 3.8+ and Cognite Toolkit

Setup Process¶

Fork the Repository

# Fork on GitHub, then clone your fork
git clone https://github.com/YOUR_USERNAME/knowledge_base.git
cd knowledge_base

Create a Branch

git checkout -b feature/your-feature-name

Install Dependencies (for documentation development)

pip install mkdocs mkdocs-material mkdocs-awesome-pages-plugin

Preview Your Changes

mkdocs serve
# Open http://127.0.0.1:8000 in your browser

📝 Content Guidelines¶

Writing Style¶

Use clear, concise language
Write for your target audience (technical vs. non-technical)
Include practical examples and use cases
Use active voice and present tense
Follow our Markdown Style Guide

Content Structure¶

Start with a clear introduction
Use hierarchical headings (H1, H2, H3)
Include a table of contents for longer documents
End with a summary or next steps
Add relevant links to related content

Quality Standards¶

Accuracy: All technical information must be verified
Completeness: Provide sufficient detail for implementation
Clarity: Use examples and diagrams where helpful
Consistency: Follow established patterns and conventions

🏗️ Template Development¶

CDF Template Requirements¶

Production Tested: All templates must be validated in real CDF environments
Error Handling: Include comprehensive error handling and validation
Documentation: Provide clear usage instructions and examples
Versioning: Use semantic versioning for template updates

Template Structure¶

# Template Name

## Overview
Brief description of what this template does and when to use it.

## Prerequisites
- Required tools and dependencies
- Access requirements
- Configuration needs

## Usage
Step-by-step instructions for using the template.

## Examples
Concrete examples with expected outputs.

## Troubleshooting
Common issues and solutions.

## Version History
- v1.0.0: Initial release
- v1.1.0: Added feature X

📋 Markdown Style Guide¶

Headers¶

Use ATX-style headers (# ## ###)
Limit to 3 levels deep when possible
Use descriptive, concise titles

Lists¶

Use single space after list markers
Use consistent indentation (4 spaces)
Prefer unordered lists for most content

Code Blocks¶

Use fenced code blocks with language specification
Include syntax highlighting where appropriate
Keep code examples concise and focused

Links¶

Use descriptive link text
Include both internal and external links
Verify all links are working

Images¶

Use descriptive alt text
Optimize images for web (compress when possible)
Include captions where helpful

🔄 Contribution Process¶

1. Planning¶

Check existing issues and discussions
Propose your contribution in an issue first
Ensure your contribution aligns with project goals

2. Development¶

Follow the content guidelines above
Test your changes locally
Ensure all links work correctly
Validate any code examples

3. Review¶

Self-review your changes
Check for typos and formatting issues
Verify technical accuracy
Test the documentation build

4. Submission¶

Commit with clear, descriptive messages
Push to your feature branch
Create a pull request with detailed description
Reference any related issues

5. Review Process¶

All contributions undergo peer review
Address feedback and requested changes
Maintainers will merge approved contributions

🛡️ Quality Assurance¶

Content Review Checklist¶

Content is accurate and up-to-date
Examples are tested and working
Links are valid and functional
Formatting follows style guide
Target audience is clearly defined
Content adds value to the knowledge base

Technical Review Checklist¶

Code examples are syntactically correct
Templates are production-ready
Error handling is comprehensive
Documentation is complete
Performance considerations are addressed

🏷️ Commit Message Guidelines¶

Use conventional commit format:

type(scope): description

[optional body]

[optional footer]

Types¶

feat: New feature or content
fix: Bug fix or correction
docs: Documentation changes
style: Formatting changes
refactor: Code restructuring
test: Adding or updating tests
chore: Maintenance tasks

Examples¶

feat(templates): add new CDF deployment template
docs(ai-knowledge): update context engineering guide
fix(links): correct broken documentation links

🎯 Recognition¶

Contributor Recognition¶

Contributors are listed in the repository README
Significant contributions are highlighted in release notes
Contributors receive recognition in project communications

Contribution Levels¶

Bronze: 1-5 contributions
Silver: 6-15 contributions
Gold: 16+ contributions or major features

🆘 Getting Help¶

Resources¶

Documentation: Check existing guides and tutorials
Issues: Search existing issues for similar questions
Discussions: Use GitHub Discussions for questions
Community: Join our community channels

Contact¶

Technical Questions: Open a GitHub issue
General Questions: Use GitHub Discussions
Urgent Issues: Contact maintainers directly

📄 License¶

By contributing to this project, you agree that your contributions will be licensed under the same license as the project (MIT License).

Thank you for contributing to the AI-Assisted Development Knowledge Base! Your contributions help make AI-assisted development more accessible and effective for everyone.