Andreas Hilbig
a01bfabfba
This commit upgrades the project to Node.js 24 (LTS) and performs a major refactoring of the documentation to support both advanced users and AI-based automation (MCP). Changes: - Environment & CI/CD: - Set Node.js version to >=24 in package.json and .nvmrc. - Updated Dockerfile to use Node 24 base image. - Updated @types/node to ^24.10.9. - Documentation: - Refactored README.md with comprehensive technical reference, configuration details, and Zabbix-to-GraphQL mapping. - Created docs/howtos/cookbook.md with practical recipes for common tasks and AI test generation. - Updated docs/howtos/mcp.md to emphasize GraphQL's advantages for AI agents and Model Context Protocol. - Added readme.improvement.plan.md to track documentation evolution. - Enhanced all how-to guides with improved cross-references and up-to-date information. - Guidelines: - Updated .junie/guidelines.md with Node 24 requirements and enhanced commit message standards (Conventional Commits 1.0.0). - Infrastructure & Code: - Updated docker-compose.yml with Apollo MCP server integration. - Refined configuration and schema handling in src/api/ and src/datasources/. - Synchronized generated TypeScript types with schema updates.
72 lines
3.4 KiB
Markdown
72 lines
3.4 KiB
Markdown
# Documentation Improvement Plan
|
|
|
|
This plan outlines the steps to refactor and improve the Zabbix GraphQL API documentation, combining a technical reference with a practical "Cookbook" for quick start and AI-based test generation.
|
|
|
|
## Priority 1: Reference Documentation (Advanced Users)
|
|
|
|
### 1.1 Enhance README.md
|
|
- **Feature-to-Code Mapping**: Add "Reference" links to each feature in the features list (from public origin).
|
|
- **Comprehensive Config Reference**: Update environment variables table with detailed descriptions, defaults, and requirements.
|
|
- **Auth Separation**: Explain `ZABBIX_PRIVILEGE_ESCALATION_TOKEN` vs `ZABBIX_DEVELOPMENT_TOKEN`.
|
|
- **Entity Mapping Table**: Include the Zabbix-to-GraphQL entity mapping table.
|
|
- **API Versioning**: Document how the version is determined and Zabbix version compatibility (7.4 focus).
|
|
|
|
### 1.2 Update Detailed Guides
|
|
- Ensure `docs/howtos/schema.md`, `permissions.md`, etc., are up-to-date with the latest implementation details.
|
|
|
|
## Priority 2: Cookbook & AI-Ready Instructions
|
|
|
|
### 2.1 Create the Cookbook (`docs/howtos/cookbook.md`)
|
|
- **Step-by-Step Recipes**: Create practical, task-oriented guides.
|
|
- **Recipe: Schema Extension**: Move the "Distance Tracker" example into the cookbook.
|
|
- **Recipe: Basic Monitoring**: Step-by-step to monitor a new host.
|
|
- **Recipe: Bulk Import**: Guide for mass importing templates and hosts.
|
|
|
|
### 2.2 AI/MCP Integration for Test Generation
|
|
- **MCP Server Documentation**: Explicitly document how to start and use the `zabbix-graphql` MCP server.
|
|
- **Test Generation Instructions**: Provide specific instructions on how an AI can use the Cookbook recipes to generate test cases.
|
|
- **Metadata for AI**: Use structured headers and clear prerequisites in recipes to make them "AI-parsable".
|
|
|
|
## Priority 3: Technical Maintenance (from Public Origin)
|
|
|
|
### 3.1 Code Generation Section
|
|
- Explain the GraphQL Codegen setup and how to regenerate types.
|
|
- Document the `codegen.ts` configuration.
|
|
- Add instructions for updating generated types after schema changes.
|
|
|
|
## Priority 4: Improve Examples
|
|
|
|
### 4.1 Complete Examples
|
|
- Add more complete examples for each major operation.
|
|
- Include error handling examples.
|
|
- Add examples for common use cases beyond the distance tracker.
|
|
|
|
### 4.2 Testing Examples
|
|
- Add information about how to run tests.
|
|
- Include examples of unit and integration tests.
|
|
- Explain the test structure and how to add new tests.
|
|
|
|
## Priority 5: Documentation Links
|
|
|
|
### 5.1 Cross-Reference Improvements
|
|
- Add links to relevant sections in schema files.
|
|
- Include references to specific resolver implementations.
|
|
- Link to related documentation files in the docs directory.
|
|
|
|
### 5.2 External Resources
|
|
- Link to official Zabbix API documentation.
|
|
- Include references to Apollo Server documentation.
|
|
|
|
## Implementation Order
|
|
1. **Foundation**: Update `README.md` with missing reference information from public origin.
|
|
2. **Cookbook Alpha**: Create `docs/howtos/cookbook.md` with the first set of recipes.
|
|
3. **AI Bridge**: Document MCP server usage and test generation workflow.
|
|
4. **Maintenance**: Add Codegen and Testing sections.
|
|
5. **Cross-Linking**: Optimize all links and cross-references.
|
|
6. **Optimize**: Run import optimization across the project.
|
|
|
|
## Success Metrics
|
|
- All environment variables documented.
|
|
- Clear distinction between Reference and Cookbook.
|
|
- Functional MCP-based test generation using cookbook instructions.
|
|
- Accurate representation of features and compatibility.
|