113 lines
3.8 KiB
Markdown
113 lines
3.8 KiB
Markdown
# QA Process & Common Pitfalls
|
|
|
|
## QA Process
|
|
|
|
**Assume there are problems. Your job is to find them.**
|
|
|
|
Your first render is almost never correct. Approach QA as a bug hunt, not a confirmation step. If you found zero issues on first inspection, you weren't looking hard enough.
|
|
|
|
### Content QA
|
|
|
|
```bash
|
|
python -m markitdown output.pptx
|
|
```
|
|
|
|
Check for missing content, typos, wrong order.
|
|
|
|
**Check for leftover placeholder text:**
|
|
|
|
```bash
|
|
python -m markitdown output.pptx | grep -iE "xxxx|lorem|ipsum|placeholder|this.*(page|slide).*layout"
|
|
```
|
|
|
|
If grep returns results, fix them before declaring success.
|
|
|
|
### Verification Loop
|
|
|
|
1. Generate slides -> Extract text with `python -m markitdown output.pptx` -> Review content
|
|
2. **List issues found** (if none found, look again more critically)
|
|
3. Fix issues
|
|
4. **Re-verify affected slides** — one fix often creates another problem
|
|
5. Repeat until a full pass reveals no new issues
|
|
|
|
**Do not declare success until you've completed at least one fix-and-verify cycle.**
|
|
|
|
### Per-Slide QA (for from-scratch creation)
|
|
|
|
```bash
|
|
python -m markitdown slide-XX-preview.pptx
|
|
```
|
|
|
|
Check for missing content, placeholder text, missing page number badge.
|
|
|
|
---
|
|
|
|
## Common Mistakes to Avoid
|
|
|
|
- **Don't repeat the same layout** — vary columns, cards, and callouts across slides
|
|
- **Don't center body text** — left-align paragraphs and lists; center only titles
|
|
- **Don't skimp on size contrast** — titles need 36pt+ to stand out from 14-16pt body
|
|
- **Don't default to blue** — pick colors that reflect the specific topic
|
|
- **Don't mix spacing randomly** — choose 0.3" or 0.5" gaps and use consistently
|
|
- **Don't style one slide and leave the rest plain** — commit fully or keep it simple throughout
|
|
- **Don't create text-only slides** — add images, icons, charts, or visual elements; avoid plain title + bullets
|
|
- **Don't forget text box padding** — when aligning lines or shapes with text edges, set `margin: 0` on the text box or offset the shape to account for padding
|
|
- **Don't use low-contrast elements** — icons AND text need strong contrast against the background
|
|
- **NEVER use accent lines under titles** — these are a hallmark of AI-generated slides; use whitespace or background color instead
|
|
- **NEVER use "#" with hex colors** — causes file corruption in PptxGenJS
|
|
- **NEVER encode opacity in hex strings** — use the `opacity` property instead
|
|
- **NEVER use async/await in createSlide()** — compile.js won't await
|
|
- **NEVER reuse option objects across PptxGenJS calls** — PptxGenJS mutates objects in-place
|
|
|
|
---
|
|
|
|
## Critical Pitfalls — PptxGenJS
|
|
|
|
### NEVER use async/await in createSlide()
|
|
|
|
```javascript
|
|
// WRONG - compile.js won't await
|
|
async function createSlide(pres, theme) { ... }
|
|
|
|
// CORRECT
|
|
function createSlide(pres, theme) { ... }
|
|
```
|
|
|
|
### NEVER use "#" with hex colors
|
|
|
|
```javascript
|
|
color: "FF0000" // CORRECT
|
|
color: "#FF0000" // CORRUPTS FILE
|
|
```
|
|
|
|
### NEVER encode opacity in hex strings
|
|
|
|
```javascript
|
|
shadow: { color: "00000020" } // CORRUPTS FILE
|
|
shadow: { color: "000000", opacity: 0.12 } // CORRECT
|
|
```
|
|
|
|
### Prevent text wrapping in titles
|
|
|
|
```javascript
|
|
// Use fit:'shrink' for long titles
|
|
slide.addText("Long Title Here", {
|
|
x: 0.5, y: 2, w: 9, h: 1,
|
|
fontSize: 48, fit: "shrink"
|
|
});
|
|
```
|
|
|
|
### NEVER reuse option objects across calls
|
|
|
|
```javascript
|
|
// WRONG
|
|
const shadow = { type: "outer", blur: 6, offset: 2, color: "000000", opacity: 0.15 };
|
|
slide.addShape(pres.shapes.RECTANGLE, { shadow, ... });
|
|
slide.addShape(pres.shapes.RECTANGLE, { shadow, ... });
|
|
|
|
// CORRECT - factory function
|
|
const makeShadow = () => ({ type: "outer", blur: 6, offset: 2, color: "000000", opacity: 0.15 });
|
|
slide.addShape(pres.shapes.RECTANGLE, { shadow: makeShadow(), ... });
|
|
slide.addShape(pres.shapes.RECTANGLE, { shadow: makeShadow(), ... });
|
|
```
|