zabbix/zabbix-graphql-api
1
0
Fork 0
Code Pull requests Activity
zabbix-graphql-api/readme.improvement.plan.md
Andreas Hilbig a9940063e9 docs: enhance cookbook recipes with verification steps and templates 
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.
2026-01-31 02:11:15 +01:00

5.2 KiB
Raw Blame History

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.

Priority 6: Refine Structure & DRY (New)

6.1 Separate Cookbook from Reference

  • Move instructional "how-to" steps from README.md to cookbook.md or specific how-tos where they distract from reference info.
  • Ensure README.md focuses on "What" (specification/reference) and cookbook.md focuses on "How" (recipes).

6.2 Eliminate Redundancy (DRY)

  • Identify and remove duplicate information between README.md and docs/howtos/ (e.g., Zabbix to GraphQL Mapping).
  • Centralize core definitions to a single source of truth and use links elsewhere.

6.3 Enhance Cross-References

  • Add explicit "See also" or "Related Recipes" links in reference sections.
  • Link from recipes back to technical reference material for deep-dives.

Priority 7: Standardization & Verification (New)

7.1 Cookbook Verification Steps

  • Add a result verification step to each recipe in cookbook.md.
  • Ensure verification steps use GraphQL queries or agent checks where appropriate.
  • Refine 'Extending Schema' recipe with detailed manual/automated steps and comprehensive verification (Priority 7 enhancement).

7.2 Recipe Templating

  • Define a standard template for recipes in .junie/guidelines.md.
  • Standardize icons and step naming (🛠️, ⚙️, 🚀, ✅).

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.
  7. Refine & DRY: Execute Priority 6 tasks to further clean up and structure documentation.
  8. 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.