90 lines
2.6 KiB
Markdown
90 lines
2.6 KiB
Markdown
# 📋 Review workflow — Review and content control
|
|
|
|
## Process
|
|
|
|
```
|
|
Draft ──→ Self-review ──→ Peer review ──→ Approval ──→ Merged
|
|
↑ │
|
|
└────────────── Feedback loop ───────────────────────┘
|
|
```
|
|
|
|
## Phases
|
|
|
|
### 1. Draft
|
|
|
|
- Author creates new content / edits existing
|
|
- Mark files as `[draft]` in the commit message note
|
|
- Goal: capture ideas, structure, and facts
|
|
|
|
### 2. Self-review (author)
|
|
|
|
- [ ] Is the content **understandable**? Would a junior understand it?
|
|
- [ ] Are the **facts correct**? Verify against sources / official documentation
|
|
- [ ] Are **sources** cited? (links in `sources/`)
|
|
- [ ] Is the **structure consistent** with the rest of the KB?
|
|
- [ ] Are **abbreviations** explained?
|
|
- [ ] **Spelling and grammar**
|
|
- [ ] Does the **tone** match — factual, without subjective opinions
|
|
- [ ] Does it contain **actionable best practices**, not just theory
|
|
|
|
### 3. Peer review (colleague / reviewer)
|
|
|
|
- Author requests a review (PR / issue / @mention)
|
|
- Reviewer checks:
|
|
- **Technical accuracy** — are data and concepts valid?
|
|
- **Completeness** — is anything important missing?
|
|
- **Impartiality** — does it not favor one vendor without reason?
|
|
- **Currency** — is any information outdated?
|
|
|
|
**Review template:**
|
|
|
|
```
|
|
## Review: [file name]
|
|
|
|
### Technical accuracy
|
|
- [ ] Facts are correct
|
|
- [ ] Recommendations are appropriate
|
|
- [ ] Cited sources are relevant
|
|
|
|
### Structure and form
|
|
- [ ] Logical structure
|
|
- [ ] Consistent formatting
|
|
- [ ] Language is understandable
|
|
|
|
### Comments
|
|
- [ ] [comment 1]
|
|
- [ ] [comment 2]
|
|
|
|
### Verdict
|
|
- [ ] Approved
|
|
- [ ] Approved with reservations (see comments)
|
|
- [ ] Rejected (reason: …)
|
|
```
|
|
|
|
### 4. Approval
|
|
|
|
- Approves: author + at least 1 peer reviewer
|
|
- After approval, content is considered `[done]`
|
|
- Changes after approval require a new review cycle
|
|
|
|
### 5. Merged / Published
|
|
|
|
- Content is considered current and trustworthy
|
|
- If a source in `sources/` is marked `[done]`, it confirms processing
|
|
|
|
## File states
|
|
|
|
| Status | Meaning |
|
|
|--------|--------|
|
|
| `[draft]` | In progress, not yet reviewed |
|
|
| `[in-review]` | Peer review in progress |
|
|
| `[done]` | Approved, current |
|
|
| `[outdated]` | Outdated, awaiting revision |
|
|
| `[deprecated]` | Replaced by another document |
|
|
|
|
## Regular revision
|
|
|
|
- **Quarterly** — check currency of the entire KB
|
|
- **Trigger** — new tool version, architecture change, EOL technology
|
|
- Each file should have a **last revision date** in its footer
|