Document entities and correct use
Created by: aydun
The background for this is the discussion on dev/membership#13 (closed) but applies more generally.
We have good docs for general usage, and for some aspects of development but we don't have anything that documents how the internal data structures relate and how to use them correctly (kinda ER but for humans!).
For example, if a membership with recurring contributions is created, what entities should result? eg membership, recurring contribution, contribution, etc. When a payment is made on that recurring contribution what should result? - contributions, payment, membership payment, line item, financial transaction, updates to membership ...
The second part of that is how each of those things is created. The line Eileen pointed out shows creating a lineitem will cause a membership payment to be created - unless it already exists, suggesting some ambiguity around whether a membership payment should have already been created. The documentation I have in mind would be something like: To create a membership with recurring contributions: create Entity1 ..., Entity2 ..., Entity3 ... and then Entity4, Entity5, Entity6 will also be created.
Our docs and API tell us for example how to create a Membership Payment, but not the bigger picture of how to correctly record a payment for membership.
A clear picture of these entity relationships and processes would provide a more robust basis for refactoring, enhancements and extensions.
Thoughts?