hackforla / hackforla/peopledepot
Create guideline for documenting clarifications
- Dominant language
- Python
- Stars
- 14
- Forks
- 37
- Avg merge
- 9d 15h
- Merged PRs (30d)
- 5
Description
### 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](https://diataxis.fr) 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 a Decision Record for what to do and why
### Resources/Instructions
- #65
- #162
- [project vs. org level sponsor/partner](https://github.com/hackforla/peopledepot/issues/65#issuecomment-1563662914)
- [better overview in #162](https://github.com/hackforla/peopledepot/issues/162#issue-1737407562)
- [diataxis applied to mkdocs](https://realpython.com/python-project-documentation-with-mkdocs/)
- [Writing docstrings for mkdocs](https://realpython.com/python-project-documentation-with-mkdocs/#step-3-write-and-format-your-docstrings) - class or module level docstrings seem useful
- [swagger API docs usage](https://drf-spectacular.readthedocs.io/en/latest/readme.html#usage)
- [Decision Records wiki pages](https://github.com/hackforla/peopledepot/wiki/Decision-Records)
#### 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.
Contributor guide
Assessment
This issue has not been assessed yet.