Attio MCP Server

# Documentation Versioning and Maintenance Guide This guide outlines our approach to maintaining and versioning the Attio MCP Server documentation. ## Documentation Structure The documentation is organized into the following categories: 1. **API Documentation** - API endpoints and operations - Request/response formats - Authentication and authorization - Error handling 2. **Integration Guides** - How to integrate with Attio MCP Server - Code examples in various languages - Use cases and scenarios 3. **Reference Material** - Complete API reference - Object schemas - Enumeration values ## Versioning Strategy ### Documentation Version Control All documentation is version-controlled in the same Git repository as the code. This ensures that documentation changes are paired with code changes and go through the same review process. ### API Versioning The Attio API uses explicit versioning in the URL (e.g., `/v2/lists`). Our documentation follows this versioning: 1. **Current Version**: The latest stable API version (currently v2) 2. **Previous Versions**: Maintained for backward compatibility 3. **Beta/Preview Features**: Clearly marked as subject to change ### Version Indicators Each API documentation file includes version information: ```markdown ## Version Information - **API Version**: v2 - **Last Updated**: YYYY-MM-DD - **Stability**: [Stable|Beta|Deprecated] ``` ## Documentation Maintenance ### Update Frequency - **Major Updates**: With each API version release - **Minor Updates**: Monthly, for clarifications and examples - **Patch Updates**: As needed for corrections ### Update Responsibilities 1. **API Developers**: Responsible for technical accuracy 2. **Technical Writers**: Responsible for clarity and consistency 3. **Product Managers**: Responsible for use cases and examples ### Update Process 1. Create a branch for documentation changes 2. Make updates following the style guide 3. Update version information 4. Submit for review 5. Address feedback 6. Merge to main ## Changelog Management Each significant documentation update should be reflected in a changelog: 1. **Added**: New documentation 2. **Changed**: Updated existing documentation 3. **Deprecated**: Documentation for deprecated features 4. **Removed**: Documentation for removed features 5. **Fixed**: Corrections to existing documentation Example: ```markdown # Documentation Changelog ## 2023-07-15 ### Added - Test coverage information to Lists API documentation - Architecture diagram for Lists API ### Changed - Updated error handling examples with more detailed explanations ### Fixed - Corrected parameter types in People API search endpoint ``` ## Documentation Testing ### Review Process All documentation changes undergo a review process to ensure: 1. **Technical accuracy**: Verified by API developers 2. **Clarity**: Verified by technical writers 3. **Completeness**: All required sections are included 4. **Example validity**: Code examples are tested ### Automated Testing 1. **Link validation**: Automated checks for broken links 2. **Code examples**: Syntax checking and execution testing 3. **Markdown formatting**: Style consistency checks ## Style Guidelines ### General Style - Use clear, concise language - Focus on how to accomplish tasks - Include examples for all operations - Use consistent terminology ### Markdown Formatting - Use ATX-style headers (`#` for titles) - Use fenced code blocks with language identifiers - Use tables for parameter descriptions - Use relative links to other documentation files ### API Documentation Template Each API documentation file should follow this structure: 1. Title and brief description 2. Version information 3. Authentication and scopes 4. Endpoints with request/response examples 5. Object schemas 6. Error handling 7. Example usage 8. Related documentation ## Visual Elements ### Diagrams - Use Mermaid diagrams for flowcharts and sequences - Embed diagrams as code and rendered images - Provide alt text for accessibility ### Code Examples - Include syntax highlighting - Show both request and response - Include error handling - Use realistic values ## Deprecation Process When API features are deprecated: 1. Mark documentation with deprecation notice 2. Include migration path to new features 3. Provide timeline for feature removal 4. Keep documentation available but clearly marked ## Documentation Tools The following tools are used for documentation: 1. **Markdown**: Primary format for documentation 2. **Mermaid**: For diagrams and flowcharts 3. **Github Pages**: For publishing documentation 4. **Markdown linters**: For style consistency ## Release Coordination Documentation releases are coordinated with code releases: 1. **Pre-release**: Draft documentation for upcoming features 2. **Release**: Publish documentation with the feature 3. **Post-release**: Update based on feedback ## Training and Onboarding New team members should: 1. Review this guide 2. Study existing documentation for style and patterns 3. Have initial documentation reviewed extensively 4. Pair with experienced documentation writers ## Issue Tracking Documentation issues are tracked in the same issue tracking system as code: 1. Label issues with `documentation` 2. Use priority levels for documentation issues 3. Link documentation issues to related code issues 4. Track documentation debt separately ## Example Workflow When updating the Lists API documentation: 1. Create branch `docs/update-lists-api` 2. Update version information in `lists-api.md` 3. Make content changes 4. Update any related diagrams 5. Test code examples 6. Update changelog 7. Submit PR with `documentation` label 8. Address review feedback 9. Merge to main ## Documentation Metrics The following metrics are tracked for documentation: 1. **Coverage**: Percentage of features with documentation 2. **Freshness**: Time since last update 3. **Completeness**: Required sections present 4. **Quality**: Issues reported per document ## Related Resources - [API Style Guide](./api-style-guide.md) - [Example Documentation Templates](./examples/) - [Documentation Issue Templates](./examples/issue-template.md)