Create guideline for documenting clarifications

[fyliu]

Dependency

• 166

• 65

• 162

Overview

We would like to come up with a guideline for where to put clarifying documentation in the code so that it's helpful for people maintaining it and using it.

Details

We can use issue #162 which has clarifying information about sponsors and partners that's not obvious which makes it more important to be documented. We can use the diataxis structure for documentation to create Reference docs for the models and APIs and Explanation docs for the sponsor/partner concept.

Action Items

• [ ] For sponsor_partner Reference
  • [ ] Add docstring to the model
  • [ ] Add docstring to the API code
  • [ ] Add markdown reference for the is_org_sponsor and is_org_partner fields
• [ ] For project_partner_xref Reference
  • [ ] Add docstring to the model
  • [ ] Add docstring to the API code
  • [ ] Add markdown reference for the is_sponsor field
• [ ] Write markdown Explanation docs to explain sponsor/partner at a high level
• [ ] Discuss in a comment below which one(s) are better / more useful
• [ ] Write a guideline or ADR for what to do and why

Resources/Instructions

• 65

• 162

• project vs. org level sponsor/partner
• better overview in #162
• diataxis applied to mkdocs
  • Writing docstrings for mkdocs - class or module level docstrings seem useful
• swagger API docs usage

Sponsor/Partner clarification (copied from #65)

Sponsor/partner relationships stored in this table are project-dependent. They cannot be both a sponsor and a partner for the same project, so if is_sponsor is FALSE they are a project partner, if is_sponsor is TRUE they are a project sponsor.

Project vs Org level clarification (copied from #65)

... sponsor/partner relationships are project-dependent, so is_sponsor stays in this table. They cannot be both a sponsor and a partner for the same project. In addition, they can also be a sponsor or partner at the org level, so the levels are:

• project partner
• project sponsor
• org partner
• org sponsor

Org level sponsors and partners (copied from #162)

There can be sponsors or partners at the org level as well as for individual projects. The same entity cannot be both a sponsor and a partner for a single project, but can be both a sponsor and a partner to the organization itself.

[fyliu]

I added #162 as a dependency. It has a more complete high-level discussion of how sponsors and partners work in the system. This can become a docs page about "Sponsors and Partners" which explains what an external entities can become sponsors and partners of. It would be helpful if it can contain links to the Reference docs for the 2 models which provide definitions of the model fields. And those model docs can reference the Explanation page.