Skip to content

Commit 32f9db4

Browse files
ascerraascerra
committed
Adding visual learning guides
dir with 7 htmls meant to help people learn the infra-deployments ecosystem holistically. - A README.md describing these htmls and how to use an LLM to easily update them or create new ones. - Updated the navigation.yaml to include a new section with this content in the published docs. Assisted-by: Cursor Signed-off-by: Adam Scerra <[email protected]>
1 parent 4ea4f56 commit 32f9db4

File tree

10 files changed

+5573
-0
lines changed

10 files changed

+5573
-0
lines changed

‎docs/_data/navigation.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,3 +55,5 @@ docs-en:
5555
url: /docs/misc/ci-helper-app.html
5656
- title: FAQs/Troubleshooting
5757
url: /docs/misc/faq.html
58+
- title: 🎨 Visual Learning Guides
59+
url: /docs/misc/visual-learning-guides/

‎docs/misc/visual-learning-guides/README.md‎

Lines changed: 225 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,225 @@
1+
---
2+
title: About Visual Learning Guides
3+
---
4+
5+
# About These Visual Guides
6+
7+
Interactive visual documentation to help understand the Konflux CI/CD platform and infra-deployments repository.
8+
9+
**→ [Browse All Visual Guides](index.html)**
10+
11+
## What Are These Guides?
12+
13+
Self-contained interactive HTML pages with:
14+
- 📊 Animated diagrams and flowcharts
15+
- 🔍 Searchable component directories
16+
- 📱 Mobile-responsive design
17+
- 🎨 Color-coded categories and difficulty levels
18+
19+
They complement the text documentation by providing visual explanations of complex workflows.
20+
21+
### How Were These Guides Created?
22+
23+
These guides were generated using **AI assistance in a Cursor workspace** that had multiple Konflux-related repositories cloned together:
24+
25+
- `redhat-appstudio/infra-deployments` - The main deployment manifests
26+
- `konflux-ci/e2e-tests` - End-to-end test suites and rules engine
27+
- `openshift/release` - OpenShift CI configuration and job definitions
28+
- `konflux-ci/architecture` - System architecture documentation
29+
- Various component repositories (build-service, integration-service, etc.)
30+
31+
**Why does this matter?** Many workflows involving infra-deployments span multiple repositories. For example:
32+
- The test selection rules that run on infra-deployments PRs are defined in `e2e-tests`
33+
- The CI job configuration lives in `openshift/release`
34+
- Component behavior that drives manifest changes is in the component repos
35+
36+
Having all these repos in the same workspace allowed the AI to research across the entire ecosystem and accurately describe how things work end-to-end, not just what's visible in infra-deployments alone.
37+
38+
**To update or create guides with full context**, clone the related repos into your workspace before asking your LLM to make changes.
39+
40+
---
41+
42+
## 🤖 Contributing with AI Assistance
43+
44+
These guides are designed to be **maintained and extended with LLM assistance** (Cursor, Copilot, Claude, etc.).
45+
46+
### Updating Existing Guides
47+
48+
When you make changes to infra-deployments that might affect a visual guide:
49+
50+
**Tell your LLM:**
51+
> "I just made changes to [describe your changes]. Check if any visual learning guides in `docs/misc/visual-learning-guides/` need to be updated. Reference the style guide in `docs/misc/visual-learning-guides/README.md` and the existing HTML files in that directory to maintain consistency."
52+
53+
**What changes trigger updates:**
54+
55+
| Your Change | Guide to Update |
56+
|-------------|-----------------|
57+
| New component in `components/` | `visual-components-map.html` |
58+
| New Kustomize overlay | `visual-kustomize-overlays.html` |
59+
| CI/testing config changes | `visual-testing-flow.html`, `visual-e2e-infra-tests.html` |
60+
| PR pairing syntax changes | `visual-pr-pairing.html` |
61+
| Renovate/MintMaker changes | `visual-renovate-workflow.html` |
62+
| Deployment pipeline/ArgoCD changes | `visual-pr-workflow.html` |
63+
64+
**Current guides:**
65+
- `index.html` - Landing page with cards linking to all guides
66+
- `visual-components-map.html` - Searchable component directory
67+
- `visual-kustomize-overlays.html` - How Kustomize overlays work
68+
- `visual-testing-flow.html` - Complete E2E testing flow
69+
- `visual-e2e-infra-tests.html` - Test selection rules for infra-deployments PRs
70+
- `visual-pr-pairing.html` - How to pair PRs across repos (Prow-specific)
71+
- `visual-pr-workflow.html` - Animated PR-to-production timeline
72+
- `visual-renovate-workflow.html` - MintMaker/Renovate automation
73+
74+
### Creating New Guides
75+
76+
To add a new visual learning guide:
77+
78+
**Tell your LLM:**
79+
> "Create a new visual learning guide about [your topic]. Read `docs/misc/visual-learning-guides/README.md` for the style guide and color palette. Use the existing HTML files in that directory as reference for structure and patterns. Research the relevant code in this repository, then generate a new HTML file following the same patterns."
80+
81+
The LLM should:
82+
1. Read `docs/misc/visual-learning-guides/README.md` for the style guide
83+
2. Read 2-3 existing HTML files in that directory to understand patterns
84+
3. Research the topic in the codebase
85+
4. Generate a new HTML file with consistent styling
86+
5. Update `docs/misc/visual-learning-guides/index.html` to add a card for the new guide
87+
88+
---
89+
90+
## 📋 Style Guide (For LLMs)
91+
92+
**This section is technical reference for AI assistants generating or updating guides.**
93+
94+
### File Structure
95+
96+
Each guide is a standalone HTML file with:
97+
- Full `<!DOCTYPE html>` document
98+
- Embedded CSS in `<style>` tags (no external stylesheets)
99+
- Embedded JavaScript in `<script>` tags (no external scripts)
100+
- No external dependencies
101+
102+
### Color Palette
103+
104+
```css
105+
/* Primary gradient (headers, accents) */
106+
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
107+
108+
/* Card backgrounds */
109+
background: white;
110+
box-shadow: 0 4px 6px rgba(0,0,0,0.1);
111+
112+
/* Difficulty tags */
113+
.beginner { background: #48bb78; } /* Green */
114+
.intermediate { background: #ed8936; } /* Orange */
115+
.advanced { background: #f56565; } /* Red */
116+
117+
/* Category colors */
118+
Success/Green: #48bb78, #10b981
119+
Warning/Orange: #ed8936, #f59e0b
120+
Info/Blue: #4299e1, #3b82f6
121+
Purple accent: #9f7aea, #764ba2
122+
Error/Red: #ef4444, #f56565
123+
```
124+
125+
### Required Elements
126+
127+
Every guide should include:
128+
129+
1. **Back link** at the top:
130+
```html
131+
<a href="index.html" class="back-link">← Back to Visual Guide Index</a>
132+
```
133+
134+
2. **Header** with gradient background:
135+
```html
136+
<div class="header">
137+
<h1>🎨 Guide Title</h1>
138+
<p>Brief description</p>
139+
</div>
140+
```
141+
142+
3. **Difficulty tags** on interactive elements:
143+
```html
144+
<span class="difficulty beginner">Beginner</span>
145+
<span class="difficulty intermediate">Intermediate</span>
146+
```
147+
148+
4. **Card-based layout** for navigation/content:
149+
```html
150+
<div class="card">
151+
<div class="card-icon">🧩</div>
152+
<h2>Section Title</h2>
153+
<p>Description text</p>
154+
</div>
155+
```
156+
157+
### Typography
158+
159+
```css
160+
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
161+
```
162+
163+
### Code Blocks
164+
165+
**IMPORTANT:** Always include `white-space: pre-wrap` to preserve line breaks:
166+
167+
```css
168+
.code-block {
169+
background: #2d3748;
170+
color: #68d391;
171+
padding: 20px;
172+
border-radius: 8px;
173+
font-family: 'Courier New', monospace;
174+
font-size: 0.9em;
175+
line-height: 1.6;
176+
white-space: pre-wrap; /* Required for line breaks! */
177+
overflow-x: auto;
178+
}
179+
```
180+
181+
### File Paths & Directory Structures
182+
183+
**Don't use code blocks for file trees** - they render poorly. Instead, use **card layouts**:
184+
185+
```html
186+
<!-- Good: Card layout for file locations -->
187+
<div style="background: #f0fff4; border-radius: 10px; padding: 20px; border-left: 4px solid #48bb78;">
188+
<h3 style="color: #2f855a;">📁 Directory Name</h3>
189+
<code style="background: #2d3748; color: #68d391; padding: 8px 12px; border-radius: 5px;">
190+
path/to/file.yaml
191+
</code>
192+
<span style="color: #48bb78; font-weight: bold;">← Description</span>
193+
</div>
194+
```
195+
196+
Use **colored boxes** with:
197+
- Blue (#4299e1) for base/shared resources
198+
- Green (#48bb78) for development
199+
- Orange (#ed8936) for staging
200+
- Red (#f56565) for production
201+
202+
### Responsive Design
203+
204+
All guides should work on mobile. Use:
205+
```css
206+
@media (max-width: 768px) {
207+
/* Mobile adjustments */
208+
}
209+
```
210+
211+
### Index Card Template
212+
213+
When adding a new guide, add this to `index.html`:
214+
```html
215+
<a href="visual-NEW-GUIDE.html" class="card">
216+
<div class="card-icon">🆕</div>
217+
<h2>Guide Title</h2>
218+
<p>Description of what this guide covers and why it's useful.</p>
219+
<span class="difficulty intermediate">Intermediate</span>
220+
<span class="card-tag">Tag</span>
221+
</a>
222+
```
223+
224+
---
225+

0 commit comments

Comments
 (0)