Skip to content

Docs: add a short 'How it works' section (cash-flow replay + DRIP + XIRR) #22

Description

@DanMat

Goal

People on Hacker News / Reddit ask how the numbers are computed. A short "How it works" section pre-empts that and builds trust.

What to do

Add a concise section to the README (or docs/HOW_IT_WORKS.md linked from the README) explaining, in plain language:

  • The event-driven replay: contributions and ex-dividend dates are merged into one chronological stream (see src/divvy/engine.py).
  • DRIP: dividends are reinvested into the same holding at that day's close.
  • Money-weighted XIRR vs. simple total return, and why it matters for lumpy contributions.
  • The contribution-free NAV used for risk metrics (drawdown/volatility) — see bucket_nav() in report.py.

Keep it short (a few short paragraphs or a bullet list). No code changes required — great non-code first contribution.

Acceptance criteria

  • A clear, accurate "How it works" section renders in the README/docs.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationgood first issueGood for newcomers

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions