zabbix/zabbix-graphql-api
1
0
Fork 0
Code Pull requests Activity

docs: enhance cookbook recipes with verification steps and templates

Browse source 
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.
This commit is contained in:
Andreas Hilbig 2026-01-31 02:11:15 +01:00
parent bbf7357e93
commit a9940063e9
3 changed files with 189 additions and 14 deletions
Download patch file Download diff file Expand all files Collapse all files

14
readme.improvement.plan.md
View file

@ -71,6 +71,17 @@ This plan outlines the steps to refactor and improve the Zabbix GraphQL API docu
- [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.
@ -79,6 +90,7 @@ This plan outlines the steps to refactor and improve the Zabbix GraphQL API docu
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.
@ -86,3 +98,5 @@ This plan outlines the steps to refactor and improve the Zabbix GraphQL API docu
- 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.