Define a practice around the documentation of our metrics
Nobody has claimed this yet.
Assessment
- Difficulty
- 5/5
- Estimated time
- Over a week
- Newbie friendliness
- 30/100
- Issue type
- Documentation
- Clarity
- Mostly clear
- Activity status
- Stale
- Domain
- documentation
Research direction
The issue names no files, tests, or entry points. Start by reviewing the proposed separation between function documentation and pkgdown articles, then clarify and agree on the metric documentation template; done means the project has an adopted practice for documenting what metrics do and why they matter.
Written by the indexing model from the issue text.
Description
This is a summary of conversations that have happened in many places.
What I'm thinking there is:
- All R package functions that "calculate" metrics must be clearly documented (obviously all functions should be documented)
- At the level of the
function, the documentation focuses exclusively on the WHAT. It is an unbiased description of what the function does, how it does this, what the parameters do and how you can use them. No description of the WHY should exist here. - At the level of the
pkgdownarticle: this is where we document the WHY. I'm thinking we could even have a "metric template" that we use to ensure each one is specifically defined. This may look something like:
Metric Documentation Template
Audience: Who do we expect to take action using this metric?
Use-Case: What action can they take? How does the metric help them take this action? (Do we expect them to take the action using this alone, or in tandem with other metrics)
Metric Proposal: In words, what does the metric do.
Metric formulation: In math, what does the metric do.
Example: A plot, or table, or something similar.
Assumptions, considerations, notes etc.
- Dominant language
- No language data
- Stars
- 3
- Forks
- 0
- PR merge metrics
- No merged PRs in 30d
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from RMI/practices
-
Difficulty 5/5 Over a week Newbie friendliness 25/100
-
Difficulty 4/5 3-5 days Newbie friendliness 35/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 35/100
-
Difficulty 5/5 Over a week Newbie friendliness 25/100
-
Difficulty 4/5 3-5 days Newbie friendliness 35/100
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
bancolombia/sentinel#22 ·
-
test md OpenCI
Difficulty 2/5 1-3 hours Newbie friendliness 74/100
-
optimization optimization:agents-md-curator
Difficulty 2/5 1-3 hours Newbie friendliness 86/100
githubnext/gh-aw-cao#13143 ·
-
Difficulty 1/5 Under an hour Newbie friendliness 94/100
objectionary/hone-maven-plugin#1061 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 85/100
redhat-developer/rhdh-plugins#4887 · 2 comments ·