מתי להשתמש
"Documentation", "Runbook", "Workflow docs", "Onboarding to automations", "Bus factor".
הוראות עבודה
1. למה זה קריטי
Workflow ללא docs = workflow שיתפוצץ כשהבונה יעזוב.
Bus factor: כמה אנשים יכולים לעזוב לפני שהמערכת קורסת? 1 = רע. 3+ = בסדר.
2. Documentation Levels
א. Inline (in workflow)
- Notes per step (Make/n8n support).
- Variable names descriptive.
- Comments in code nodes.
ב. Workflow README
- 1-page summary per workflow.
- What it does, who owns, when to use.
ג. System Documentation
- Architecture overview.
- Tools inventory.
- Cross-references.
ד. Runbooks
- "When X happens, do Y".
- Incident response.
- Common issues + fixes.
3. Workflow README Template
# Workflow: [Name]
## Purpose
[1-2 sentences: what does this do, why does it exist]
## Owner
- Primary: [Name] (Slack: @handle)
- Backup: [Name]
## Schedule
- Trigger: [event / cron]
- Frequency: [hourly / daily / on-demand]
## Architecture
- Source: [where data comes from]
- Tool: [Zapier/Make/n8n]
- Destinations: [where data goes]
## Dependencies
- API keys: [list, where stored]
- Tools: [HubSpot, Slack, etc.]
- Other workflows that feed this / depend on this
## Volume + Cost
- Average runs/month: X
- Cost: $Y/m
- ROI: $Z saved
## Known Issues
- [Issue]: [Workaround]
## Change Log
- 2026-05-07 — Created (Dana)
- 2026-05-15 — Added retry logic (Avi)
4. Where to Store Docs
Options
- Notion — most flexible, searchable.
- Confluence — Enterprise.
- GitHub README — for tech teams.
- Airtable base — structured.
- Inline in tool — limited.
Recommendation
- Notion with database + template.
5. Naming Conventions
Workflows
[Department]_[Trigger]_[Action]- e.g.,
Sales_NewLead_RouteToSDR - e.g.,
Finance_NewInvoice_SubmitForApproval
Folders
- By department or by use case.
Variables
- Descriptive:
{{lead_email}}not{{x1}}.
6. Diagrams
Tools
- Lucidchart, Miro, Whimsical, Excalidraw.
- Mermaid (text-based diagrams in Markdown).
What to Diagram
- High-level architecture.
- Critical workflows.
- Decision trees.
Example Mermaid
graph TD
A[New Lead] --> B{Score > 50?}
B -->|Yes| C[Notify Sales]
B -->|No| D[Add to Nurture]
C --> E[CRM Update]
D --> E
7. Auto-Generated Docs
Tools
- n8n: workflow JSON exportable.
- Make: scenario blueprint exportable.
- Custom scripts: pull from API → Markdown.
Example
- Weekly script pulls all workflows → generates inventory page.
8. Maintenance
Quarterly Review
- All workflow READMEs current?
- Owners still in company?
- Volume/cost data updated?
- Deprecated workflows archived?
On Change
- Update README.
- Add to change log.
- Notify stakeholders if breaking.
9. Onboarding New Team Member
Day 1
- README of all workflows they'll touch.
- System overview doc.
- Access to all tools (with view-only first).
Week 1
- Shadow existing workflows.
- Modify a low-stakes workflow.
- Review-by-buddy before deploy.
10. Common Pitfalls
❌ Docs in person's head — fired/quit = lost. ❌ Outdated docs worse than no docs. ❌ Over-documented trivia, under-documented critical. ❌ No ownership — docs orphan.
11. Israeli Context
- Hebrew documentation OK, English preferred for tools.
- Bilingual — descriptions in Hebrew, technical names in English.
12. אסיים בהמלצה.
קלט נדרש
| פריט | תיאור |
|---|---|
| Workflows count | total |
| Current docs | none / scattered / good |
| Team size | who maintains |
פלט צפוי
| רכיב | תיאור |
|---|---|
| Docs structure | Notion DB / Confluence / etc |
| Templates | README, Runbook |
| Naming convention | proposed |
| Maintenance cadence | quarterly |
| המלצה | פעולה אחת |
דגלים אדומים
- 🚨 No docs — bus factor 1.
- 🚨 Outdated docs — worse than none.
- 🚨 No owner assigned per workflow.
הערות חשובות
- Effort: 30 min per workflow upfront.
- ROI: invaluable on incident.
- Living docs — update as you go.
פרומפט לדוגמה
50 Zaps, no docs. תכנון מ-0.
Notion template ל-workflow doc.
איך לשמור docs מסונכרנים עם workflows?
© 2026 Automation Expert Pro | גרסה 1.0.0