hackforla / hackforla/peopledepot

Create guideline for documenting clarifications

Open
#182 1 comment 0 reactions 0 assignees View on GitHub
complexity: missing feature: docs: PD team documentation feature: DR feature: process improvement p-feature: sponsor/partner PII: FALSE ready for dev lead role: dev lead role: technical writing s: PD team size: 3pt
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.