Add documentation about common Membership and Post cases

[jpmckinney]

• [ ] When to use Posts (what they are for, why you would use them)
• [ ] Whether to store a property value (like "role”) on both the Membership and the Post or on only one
• [ ] When to add contact details on Person versus Membership versus Post
• [ ] How to model party and caucus memberships (when does each start and end, relationship to legislative membership), what party and caucus membership mean
• [ ] Whether/in what cases to model party memberships, caucus memberships or both
• [ ] What onBehalfOf is for (e.g. see https://github.com/mysociety/yournextmp-popit/issues/78) (in legislative context, it would mean "caucus" and not "party" though the two are often conflated in jurisdictions where there's little distinction)

For each of these topics, add a short discussion to each affected spec, and link to the additional documentation.

Discuss trade-offs by answering questions like:

"Doing things like adds more complexity, but makes it simpler to run sort of query"

"This way is technically more precise, but unless you actually need to track X, then it might be simpler to just do it this way instead"

[guglielmo]

On the first point, when to use Posts, some sketched diagrams, to understand how the same situation could be modeled, using Posts or not. The Use Case is that of a local institution (the city of Rome), which has 3 sub-institutions: the Mayor, the Council (legislative), the Government (executive).

The first model uses Posts.

• memberships are simple,
• it is immediate to get all members of the council
• roles are mostly defined in Posts, only some roles are used in memberships, when the member has some extra role (the President of the Council, or to specify competences in the Government)

The second model does not use Posts, and all memberships are a-like.

• memberships are complex
• roles must be explicit in each membership
• to extract all counselors, one need to actually know that the President of the Council is also a member, and the query is complex

The third model does not use Posts, but a hierarchy of sub-organizations is used.

• memberships are clear
• queries are straightforward

In this case I feel like I'd choose between the first and the third pattern.

[dracos]

On the onBehalfOf point, when modelling some UK MPs, doing it "properly" (i.e. with separate memberships for party membership and for House of Commons membership, using posts for the latter) seems to lead to some complex explanations/code as to how to work out an MP's current party or constituency (e.g. "you want the membership which has no end date, associated with an organisation whose classification is party"). So I think onBehalfOf here makes sense as it makes such queries simpler (and also makes it simpler if an MP is also a representative in another body in the same data output but in a different party).

[jpmckinney]

Yes, I am leaning towards recommending onBehalfOf and not using a separate party membership (except in the case where you really do want to model their joining and leaving of the party outside the context of being a member of the legislature).

[jpmckinney]

@guglielmo To confirm, based on discussions last week, the year 2013 in the diagrams can be ignored? In that case, yes, it makes sense to have an organization for the city as a whole, and then suborganizations for the government (executive) and council (legislative). That's how I'm modeling the City of Montreal, except I also create posts within those suborganizations.

[guglielmo]

Yes, I am modeling Italian local administrations this way (look, no Posts!).

+---------------------+                                                                    
| ORGANIZATION        |                                                                    
| ORG: Comune di Roma |                                                                    
+----------+----------+                                                                    
           |                                                                               
           |                                                                               
           |                                                                               
           |    +--------------------------+           +------------+          +----------+
           |    | ORGANIZATION             +----+------+ MEMBERSHIP +----------+  PERSON  |
           +----+ Name: Consiglio Comunale |    |      +------------+          +----------+
           |    | di Roma 2013             |    |                                          
           |    +--------------------------+    |      +------------------+    +----------+
           |                                    +------+ MEMBERSHIP       +----+  PERSON  |
           |                                           | role: Presidente |    +----------+
           |                                           +------------------+                
           |                                                                               
           |    +--------------------------+                                               
           |    | ORGANIZATION             |           +-------------------+   +----------+
           +----+ Name: Giunta Comunale    +----+------+ MEMBERSHIP        +---+  PERSON  |
                | di Roma 2013             |    |      | role: Sindaco     |   +----------+
                +--------------------------+    |      +-------------------+               
                                                |                                          
                                                |      +-------------------+   +----------+
                                                +------+ MEMBERSHIP        +---+  PERSON  |
                                                       | role: Vicesindaco |   +----------+
                                                       +-------------------+               

[jpmckinney]

Nice use of http://asciiflow.com/ :) I can use this as part of the new documentation.

[kaerumy]

For our use cases in Malaysia we prefer a single universal database for the whole country, and would therefore prefer @guglielmo first model. This is because we would like to easily query all posts held by someone and their relations to organizations (political parties, NGOs, companies) easily. Similarly we would make sub-organizations also rather than second pattern.

The first pattern works better for us, so that we can flexibly model different types of organizations easily, especially standard corporations which have Board of Directors and Management (CxO) members.

Similar to @guglielmo, except instead of competencies, for memberships, role would be used instead of competencies to be specific teams such as: Board of Directors, Board of Advisors, Executive Committee, Supreme Council etc.

For management team in a company where there is always Posts, we would still have role in Membership (Management), but also role for Post eg. CEO.

This is typical organization of a Malaysian government owned or linked company: http://www.1mdb.com.my/governance/senior-leadership

The use of Role (Function) here didn't seem to quite fit into the existing documentation for Posts & Membership in Popolo spec so I got a bit confused if how I used roles, was OK or not.

[jpmckinney]

role should not be used to refer to an organization. You just just create a sub-organization, and make people members of that suborganization. Otherwise, it sounds fine!