Andreas Hilbig
a9940063e9
This commit refines the project documentation by adding result verification steps to all recipes in the cookbook and formalizing documentation standards in the project guidelines.
Changes:
- docs/howtos/cookbook.md:
- Added 'Verify' steps to all recipes using GraphQL queries or agent checks.
- Enhanced 'Extending Schema with a New Device Type' recipe:
- Updated Step 1 with a realistic schema using 'DistanceTrackerDevice' implementing 'Host' and 'Device' interfaces.
- Added mandatory advice for new device types to implement 'Host' and 'Device'.
- Referenced the existing 'location_tracker_devices.graphql' as a prepared real-world sample.
- Split Step 3 into Method A (Manual Creation) and Method B (Automated Import).
- Expanded Step 4 with a host creation step (using importHosts) and a filtered allDevices query using tag_deviceType.
- Standardized icons for preparation (🛠️), configuration (⚙️), execution (🚀), and verification (✅).
- .junie/guidelines.md:
- Added 'Documentation Templates' section defining a formal Recipe Template.
- Standardized icons and step naming to maintain visual consistency across all guides.
- Added 'Review & Approval' rule to prevent automatic commits without user review.
- readme.improvement.plan.md:
- Added and completed 'Priority 7: Standardization & Verification' tasks.
- Updated implementation order to reflect the new standardization phase.
102 lines
5.2 KiB
Markdown
102 lines
5.2 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
|
|
- [x] **Feature-to-Code Mapping**: Add "Reference" links to each feature in the features list (from public origin).
|
|
- [x] **Comprehensive Config Reference**: Update environment variables table with detailed descriptions, defaults, and requirements.
|
|
- [x] **Auth Separation**: Explain `ZABBIX_PRIVILEGE_ESCALATION_TOKEN` vs `ZABBIX_DEVELOPMENT_TOKEN`.
|
|
- [x] **Entity Mapping Table**: Include the Zabbix-to-GraphQL entity mapping table.
|
|
- [x] **API Versioning**: Document how the version is determined and Zabbix version compatibility (7.4 focus).
|
|
|
|
### 1.2 Update Detailed Guides
|
|
- [x] 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`)
|
|
- [x] **Step-by-Step Recipes**: Create practical, task-oriented guides.
|
|
- [x] **Recipe: Schema Extension**: Move the "Distance Tracker" example into the cookbook.
|
|
- [x] **Recipe: Basic Monitoring**: Step-by-step to monitor a new host.
|
|
- [x] **Recipe: Bulk Import**: Guide for mass importing templates and hosts.
|
|
|
|
### 2.2 AI/MCP Integration for Test Generation
|
|
- [x] **MCP Server Documentation**: Explicitly document how to start and use the `zabbix-graphql` MCP server.
|
|
- [x] **Test Generation Instructions**: Provide specific instructions on how an AI can use the Cookbook recipes to generate test cases.
|
|
- [x] **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
|
|
- [x] Explain the GraphQL Codegen setup and how to regenerate types.
|
|
- [x] Document the `codegen.ts` configuration.
|
|
- [x] Add instructions for updating generated types after schema changes.
|
|
|
|
## Priority 4: Improve Examples
|
|
|
|
### 4.1 Complete Examples
|
|
- [x] Add more complete examples for each major operation.
|
|
- [x] Include error handling examples.
|
|
- [x] Add examples for common use cases beyond the distance tracker.
|
|
|
|
### 4.2 Testing Examples
|
|
- [x] Add information about how to run tests.
|
|
- [x] Include examples of unit and integration tests.
|
|
- [x] Explain the test structure and how to add new tests.
|
|
|
|
## Priority 5: Documentation Links
|
|
|
|
### 5.1 Cross-Reference Improvements
|
|
- [x] Add links to relevant sections in schema files.
|
|
- [x] Include references to specific resolver implementations.
|
|
- [x] Link to related documentation files in the docs directory.
|
|
|
|
### 5.2 External Resources
|
|
- [x] Link to official Zabbix API documentation.
|
|
- [x] Include references to Apollo Server documentation.
|
|
|
|
## Priority 6: Refine Structure & DRY (New)
|
|
|
|
### 6.1 Separate Cookbook from Reference
|
|
- [x] Move instructional "how-to" steps from README.md to `cookbook.md` or specific how-tos where they distract from reference info.
|
|
- [x] Ensure `README.md` focuses on "What" (specification/reference) and `cookbook.md` focuses on "How" (recipes).
|
|
|
|
### 6.2 Eliminate Redundancy (DRY)
|
|
- [x] Identify and remove duplicate information between `README.md` and `docs/howtos/` (e.g., Zabbix to GraphQL Mapping).
|
|
- [x] Centralize core definitions to a single source of truth and use links elsewhere.
|
|
|
|
### 6.3 Enhance Cross-References
|
|
- [x] Add explicit "See also" or "Related Recipes" links in reference sections.
|
|
- [x] Link from recipes back to technical reference material for deep-dives.
|
|
|
|
## Priority 7: Standardization & Verification (New)
|
|
|
|
### 7.1 Cookbook Verification Steps
|
|
- [x] Add a result verification step to each recipe in `cookbook.md`.
|
|
- [x] Ensure verification steps use GraphQL queries or agent checks where appropriate.
|
|
- [x] Refine 'Extending Schema' recipe with detailed manual/automated steps and comprehensive verification (Priority 7 enhancement).
|
|
|
|
### 7.2 Recipe Templating
|
|
- [x] Define a standard template for recipes in `.junie/guidelines.md`.
|
|
- [x] Standardize icons and step naming (🛠️, ⚙️, 🚀, ✅).
|
|
|
|
## Implementation Order
|
|
1. [x] **Foundation**: Update `README.md` with missing reference information from public origin.
|
|
2. [x] **Cookbook Alpha**: Create `docs/howtos/cookbook.md` with the first set of recipes.
|
|
3. [x] **AI Bridge**: Document MCP server usage and test generation workflow.
|
|
4. [x] **Maintenance**: Add Codegen and Testing sections.
|
|
5. [x] **Cross-Linking**: Optimize all links and cross-references.
|
|
6. [x] **Optimize**: Run import optimization across the project.
|
|
7. [x] **Refine & DRY**: Execute Priority 6 tasks to further clean up and structure documentation.
|
|
8. [x] **Standardize**: Add verification steps and formalize the recipe template (Priority 7).
|
|
|
|
## 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.
|
|
- Zero redundant tables or instructional blocks across the doc set.
|
|
- All recipes include a verification step.
|
|
- Guidelines contain a clear template for future recipes.
|