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.
This commit is contained in:
parent
bbf7357e93
commit
a9940063e9
3 changed files with 189 additions and 14 deletions
|
|
@ -53,6 +53,45 @@ The [Roadmap](../roadmap.md) is to be considered as outlook giving constraints o
|
|||
- *Format*: Use plain text for general descriptions that follow a primary list item.
|
||||
- **Formatting**: Avoid extra blank lines between headers and list items.
|
||||
|
||||
## Documentation Templates
|
||||
|
||||
### Cookbook & Recipes
|
||||
Follow this template for all cookbook entries to ensure consistency and AI-parsability.
|
||||
|
||||
#### Recipe Template
|
||||
```markdown
|
||||
## 🍳 Recipe: [Action-Oriented Title]
|
||||
|
||||
[Brief description of what this recipe achieves.]
|
||||
|
||||
### 📋 Prerequisites
|
||||
- [Constraint 1]
|
||||
- [Constraint 2]
|
||||
|
||||
### 🛠️ Step 1: [Preparation/Definition]
|
||||
[Instructions for preparing data or environment.]
|
||||
|
||||
### ⚙️ Step 2: [Configuration/Settings]
|
||||
[Instructions for configuring settings or environment variables.]
|
||||
|
||||
### 🚀 Step 3: [Execution/Action]
|
||||
[The main GraphQL operation or command to execute.]
|
||||
|
||||
### ✅ Step 4: [Verification]
|
||||
[How to verify that the operation was successful using a query or agent check.]
|
||||
```
|
||||
|
||||
#### Standard Icons for Steps
|
||||
- 🍳 **Recipe**: Main header icon.
|
||||
- 📋 **Prerequisites**: Necessary conditions before starting.
|
||||
- 🛠️ **Preparation**: Initial setup, data definition, or file creation.
|
||||
- ⚙️ **Configuration**: Changes to settings, `.env`, or Zabbix UI.
|
||||
- 🚀 **Execution**: The primary action or mutation.
|
||||
- ✅ **Verification**: Result checking and outcome validation.
|
||||
- 💡 **Tip/Alternative**: Helpful hints or alternative methods.
|
||||
- 🤖 **AI/MCP**: Agent-specific instructions.
|
||||
|
||||
### Git Standards
|
||||
- **Commit Messages:** Use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) (e.g. `feat:`, `fix:`, `chore:`, `docs:`, `test:`, `refactor:`, `style:`).
|
||||
- If a commit is complex and covers different aspects, the message **must** always contain a detailed list of what was changed within the optional "body" section, in addition to the short "description" in the header.
|
||||
- **Review & Approval**: Never commit changes automatically. Always present the proposed changes and the updated plan to the user for review. Allow the user to provide feedback or add tasks to the plan before proceeding with a commit.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue