Skip to content

SDLC Documentation Framework

Purpose: Define the documentation standard used across all blueprints in this repo.

Source: Adapted from the CUT Department of ICT & Electronics Attachment Project Report Guidelines (Chapters 1–5 + Appendices). CUT's structure is a Waterfall-derived academic template designed to prove a student followed a process to an examiner. We keep the parts that force clear thinking. We drop the parts that exist only to satisfy a marking rubric.

Principle: A document earns its place only if someone would make a different decision after reading it. If removing a section changes nothing about what we build, it doesn't belong.

1. What we kept, dropped, and why

CUT section Our equivalent Decision Reason
1.1 Background Problem Definition §1 — Context Keep, expand The single most important section. CUT treats it as a paragraph; we treat it as the whole case.
1.1.2 Company Organogram Ownership & Responsibilities matrix Transform A 1–2 person company has no organogram. What matters is who owns which function and who decides.
1.1.3–1.1.4 Vision / Mission One-line thesis Compress Vision statements are decoration at pre-revenue stage. One sentence of strategy beats a page of aspiration.
1.2 System's Request Summary (dropped) Drop Assumes an external client commissioned the work. We are the client.
1.3 Problem Definition Problem Definition §1–§2 Keep, expand Core. We add evidence, frequency, and cost-of-inaction.
1.4 Aim Objective statement Keep Forces a single sentence answer to "what are we actually doing?"
1.5 Objectives (SMART) Success metrics with thresholds Keep, harden CUT says "SMART"; we make every objective numerically falsifiable with a kill threshold.
1.6 Constraints Constraints & Assumptions Keep Genuinely useful — budget, solo capacity, data costs, regulation.
1.7 Justification Why now / why us Keep CUT's version is weak ("it will help the company"). Ours is founder-market fit + timing.
2.1 Business Value Business model & value capture Keep, sharpen Who pays, how much, how often. CUT treats this as an afterthought.
2.2 Feasibility (Technical / Operational / Economic) Feasibility Study Keep as-is This triad is genuinely sound and maps cleanly to reality.
2.3 Risk Analysis Risk register (likelihood × impact × mitigation × owner) Keep, upgrade CUT asks for a list. We ask for a mitigation and an owner per risk.
2.4 Project Plan / Schedule / Gantt Stage-gated delivery plan Transform Gantt charts are fiction for solo founders. Replace with gate-based milestones and explicit kill criteria.
3.1 Information Gathering Methodologies Validation methods Keep, compress One short section on how we'll test assumptions is enough.
3.2 Analysis of existing system Competitive landscape Keep, reframe "Existing system" = whatever people do today, including WhatsApp and nothing.
3.3 Process Analysis Current-state user journey Keep Walking the as-is flow is how you find the real friction.
3.4 Data Analysis (Context Diagram, DFD) System context (C4 Level 1) Keep, replace notation DFDs are legacy. C4 context diagrams carry the same information with less ceremony.
3.5 Weaknesses in current system Gap analysis Keep What today's workaround fails to do.
3.6 Evaluation of Alternatives Build / Buy / Integrate / Do nothing Keep Still the right question.
3.7.1 Functional Requirements FR table with IDs + MoSCoW Keep, harden Every FR gets an ID so tests and scope can trace back to it.
3.7.2 Non-Functional Requirements NFR table with measurable targets Keep, harden CUT says "the system should be fast". We say "< 3s cold start on a $60 Android over 3G".
4.1–4.2 System / Architectural Design C4 Levels 1–3 Keep, replace notation Context → Container → Component. Skip Level 4 (code) — the repo is the code.
4.3 Physical Design (dropped) Drop "Physical design" means server rooms and cabling. Everything is cloud.
4.4 Database Design ERD + schema + data dictionary Keep, upgrade ERD and data dictionary are still the right artefacts.
4.5.1 Package Diagram (dropped) Drop Low information density at this stage. Directory structure in the repo covers it.
4.5.2 Class Diagram Type/domain model (selective) Keep Only where domain logic is non-obvious (e.g. service-due calculation).
4.5.3 Sequence Diagram Sequence diagrams for critical flows Keep The three flows that must not break.
4.5.4–4.5.5 Context / DFD (repeated) (merged into 4.1–4.2) Drop duplicate CUT lists the same artefacts twice across chapters. We list each once.
4.6 Interface Design UX flows + screen inventory Keep, expand The interface is the product in a low-trust market.
4.6.1 Security Design Security & privacy design Keep, expand CUT means "login screen". We mean auth model, RLS, data protection, payment security.
4.6.2–4.6.3 Input / Output Design Input & output design Keep Especially output: what the user receives when the app is closed (WhatsApp, PDF, receipt).
5.1 Coding Implementation notes Compress Git history replaces prose about code.
5.2.1–5.2.4 Unit / Modular / Objectives / Acceptance Testing Testing strategy (pyramid + UAT) Keep, modernise Unit → integration → E2E → UAT.
5.2.5 Validation Problem validation Keep "Did we build the right thing?" — measured against usage, not opinion.
5.2.6 Verification Build verification Keep "Did we build the thing right?" — tests, acceptance criteria, code review.
5.3.1 Hardware Installation (dropped) Drop No hardware.
5.3.2–5.3.4 Software / Database / Application Installation Deployment & release process Keep, merge One section: how code gets to production and how it gets rolled back.
5.3.5 Training Onboarding design Transform For a consumer app, "training" = first-run experience and garage onboarding script.
5.3.6 Review Post-launch review cadence Keep Weekly metrics review + monthly retro.
5.3.7 Back-up Backup & disaster recovery Keep, harden RPO/RTO targets, restore drills.
Appendix A: User Manual Appendix: user manual Keep as appendix Still useful for garage-side users.
Appendix B: Sample Code (dropped) Drop The repository is the sample code.
Appendix C: Research Methodologies Validation log Keep, compress Sources and assumption tests live in one place.

2. The blueprint structure

Every idea that gets a full blueprint uses these documents, in this order:

00-executive-summary.md          One page. Verdict, thesis, numbers, kill criteria.
01-problem-definition.md         Context, evidence, who hurts, what they do today, cost of inaction.
02-market-and-competition.md     Sizing, segments, existing alternatives, why now, why us.
03-feasibility-and-alternatives.md  Technical / operational / economic feasibility; build vs buy vs integrate vs nothing.
04-requirements-specification.md    Personas, FR IDs, NFR targets, out-of-scope, acceptance criteria.
05-solution-design.md            C4 context/container/component, critical sequence flows, algorithm design.
06-data-design.md                ERD, schema, data dictionary, retention.
07-interface-design.md           Screen inventory, key journeys, input design, output design, security design.
08-delivery-plan.md              Stage gates with exit criteria and kill criteria.
09-testing-strategy.md           Test pyramid, UAT, validation vs verification, release criteria.
10-operations-manual.md          Deployment, monitoring, backups/DR, support, incident runbook.
11-business-model.md             Pricing, unit economics, financial model, go-to-market.
12-risk-register.md              Likelihood × impact × mitigation × owner × trigger.
13-open-questions.md             Decisions pending, experiments queued, assumptions to test.

Not every idea warrants the full set. Ideas ranked 3–5 get a parked memo: the problem, why it lost, and the specific trigger that would make us reopen it. Writing a full blueprint for an idea we're not doing is waste.

3. Numbering and conventions

  • Requirements: FR-<MODULE>-<NN> for functional, NFR-<CATEGORY>-<NN> for non-functional.
  • Risks: R-<NN>, with a named owner and an observable trigger.
  • Gate criteria: binary. A gate is passed or not passed. "Partly done" is not a state.
  • Money: USD unless stated. Zimbabwe operates a dual USD/ZiG reality; all internal accounting is USD, ZiG is a display currency only.
  • Dates: ISO-8601.
  • Diagrams: Mermaid, in-line, in the markdown. They diff and review like code.

4. What "specific to the point" means here

A section passes review if it satisfies all three:

  1. Falsifiable — it makes a claim that could be proven wrong.
  2. Actionable — it changes what gets built, priced, or prioritised.
  3. Sourced or flagged — numbers are cited or explicitly marked as an estimate with the basis stated.

Sections that fail are deleted, not padded.